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 It is an expansion error if the result of an expression is not defined
1466 in C.
1467 Brace expansion
1469 Brace expansion expands to several split words with preceding and
1470 succeeding portions duplicated to each split words. Brace expansion is
1471 expanded only when the brace-expand option is enabled.
1472 Comma-separated brace expansion
1474 {word1,word2,...,wordn}
1475 Range brace expansion
1477 {start..end}
1478 {start..end..delta}
1480 Comma-separated brace expansion is expanded to each comma-separated
1482 word. For example, a{1,2,3}b is expanded to the three words a1b, a2b,
1483 and a3b.
1484 Range brace expansion is expanded to integers in the range defined by
1486 start and end. The difference between each integer can be defined by
1487 delta. If start is larger than end, the results will be in descending
1488 order. When ..delta is omitted, it defaults to 1 or -1. For example,
1489 a{1..3}b is expanded to the three words a1b, a2b, and a3b; and
1490 a{1..7..2}b to the four words a1b, a3b, a5b, and a7b.
1491 Multiple brace expansions can be used in one word. Brace expansions can
1493 also be nested. You can quote braces and/or commas to prevent them from
1494 being treated as brace expansion.
1495 Any errors in brace expansion are silently ignored.
1497 Field splitting
1499 In field splitting, words are split at predefined separators.
1500 Field splitting can occur only within parts of words that resulted from
1502 parameter expansion, command substitution, and arithmetic expansion
1503 that are not between double-quotation marks. Expansion results of the @
1504 special parameter are exceptionally split even between double-quotation
1505 marks.
1506 Separators used in field splitting are defined by the value of the IFS
1508 variable. If the variable does not exist, the value is assumed to be
1509 the three characters of space, tab, and newline.
1510 Characters included in the value of the IFS variable are called IFS
1512 characters. IFS characters that are any of space, tab, and newline are
1513 called IFS whitespace and other IFS characters are called IFS
1514 non-whitespace.
1515 Field splitting is performed as follows:
1517 1. The shell searches words for split points. A split point is one or
1519 more adjacent IFS characters within the word portions where field
1520 splitting can occur. The following steps are taken for each split
1521 point found.
1522 2. If the split point includes one or more IFS non-whitespaces, all
1524 the IFS whitespaces in the split point are ignored and the word is
1525 split at each IFS non-whitespace in the split point.
1526 3. If the split point includes no IFS non-whitespaces, the word is
1528 split at the split point unless it is at the beginning or end of
1529 the word.
1530 4. The split points are removed from the results.
1532 Finally, the last word is removed from the results if:
1534 • the empty-last-field option is not enabled;
1536 • the result is more than one word; and
1538 • the last word is empty.
1540 Note
1542 Words are not split at all when the value of the IFS variable is
1543 empty.
1544 Pathname expansion
1546 Pathname expansion performs pattern matching and expands to pathnames
1547 matched by the pattern.
1548 A word subjected to pathname expansion is treated as a pattern. If one
1550 or more pathnames are found that are matched by the pattern, the
1551 pathnames become the results of the pathname expansion.
1552 Pathname expansion is not performed when the glob option is disabled.
1554 The shell searches readable directories for matching pathnames.
1556 Unreadable directories are silently ignored.
1557 The following options affect the behavior of pathname expansion:
1559 null-glob
1561 This option affects the result of pathname expansion when no
1562 matching pathnames are found. If enabled, the result is no word. If
1563 disabled, the result is the original pattern word.
1564 case-glob
1566 This option specifies case-sensitivity in matching. If enabled,
1567 pattern matching is done case-sensitively.
1568 dot-glob
1570 This option affects matching of filenames that start with a period
1571 (.). If disabled, a period at the beginning of a filename does not
1572 match wildcard patterns (? and *) or bracket expressions. If
1573 enabled, there is no such special treatment of periods.
1574 mark-dirs
1576 If enabled, each resulting pathname that is a directory name is
1577 suffixed by a slash (/).
1578 extended-glob
1580 This option enables the extension. (See below)
1581 Any errors in pathname expansion are silently ignored. If the word is
1583 an invalid pattern, it just becomes the result. The results depend on
1584 the null-glob option when no matching pathnames are found.
1585 Pattern matching is done for each filename (or pathname component) of
1587 pathnames. The shell skips matching for literal patterns that contain
1588 no wildcards or bracket expressions. As a result, the patterns /*/foo
1589 and /*/fo[o] may yield different expansion results when the case-glob
1590 option is disabled; for example, the pattern /*/fo[o] matches the
1591 pathname /bar/FOO but the pattern /*/foo does not because matching is
1592 skipped for foo.
1593 Extension in pathname expansion
1595 The following patterns can be used when the extended-glob option is
1596 enabled.
1597 **
1599 The directory is searched recursively and the pattern matches
1600 any number of directory filenames (each separated by a slash).
1601 Any directory whose name begins with a period is excluded from
1602 search. For example, the pattern dir/**/file can match the
1603 pathnames dir/file, dir/foo/file, dir/a/b/c/file, etc.
1604 This pattern is not effective when appearing at the end of the
1606 whole pattern (i.e. foo/bar/**).
1607 .**
1609 This pattern is like **, but all directories are searched
1610 including ones with a name starting with a period.
1611 ***
1613 This pattern is like **, but if a symbolic link to a directory
1614 is found during recursive search, the directory is searched
1615 recursively as well.
1616 .***
1618 This pattern is like ***, but all directories are searched
1619 including ones with a name starting with a period.
1620
1622 Pattern matching notation is a syntax of patterns that represent
1623 particular sets of strings. When a string is included in the set of
1624 strings a pattern represents, the pattern is said to match the string.
1625 Whether a pattern matches a string or not is defined as follows.
1626 Normal characters
1628 A character that is not quoted or any of special characters defined
1629 below is a normal character, which matches the character itself.
1630 For example, the pattern abc matches the string abc, and not any other
1632 strings.
1633 Single-character wildcard
1635 The character ? matches any single character.
1636 For example, the pattern a?c matches any three-character strings that
1638 starts with a and ends with c, such as aac, abc, and a;c.
1639 Multi-character wildcard
1641 The character * matches any strings (of any length, including the empty
1642 string).
1643 For example, the pattern a*c matches any string that starts with a and
1645 ends with c, such as ac, abc, and a;xyz;c.
1646 Bracket expression
1648 A pattern that is enclosed by brackets ([ and ]) is a bracket
1649 expression. A bracket expression must have at least one character
1650 between the brackets. The characters between the brackets are
1651 interpreted as a bracket expression pattern, which is a below-defined
1652 special notation for bracket expression. A bracket expression pattern
1653 represents a set of characters. The bracket expression matches any one
1654 of the characters in the set the bracket expression pattern represents.
1655 If the opening bracket ([) is followed by an exclamation mark (!), the
1657 exclamation is not treated as part of the bracket expression pattern
1658 and the whole bracket expression instead matches a character that is
1659 not included in the set the bracket expression pattern represents. If
1660 the opening bracket is followed by a caret (^), it is treated like an
1661 exclamation mark as above (but shells other than yash may treat the
1662 caret differently).
1663 If the opening bracket (or the following exclamation or caret, if any)
1665 is followed by a closing bracket (]), it is treated as part of the
1666 bracket expression pattern rather than the end of the bracket
1667 expression. You cannot quote characters in the bracket expression
1668 pattern because quotation is treated before bracket expression.
1669 An opening bracket in a pattern is treated as a normal character if it
1671 is not the beginning of a valid bracket expression.
1672 Normal characters (in bracket expression pattern)
1674 A character that is not any of special characters defined below is a
1675 normal character, which represents the character itself.
1676 For example, the bracket expression pattern abc represents the set of
1678 the three characters a, b, and c. The bracket expression [abc]
1679 therefore matches any of the three characters.
1680 Range expressions
1682 A hyphen preceded and followed by a character (or collating symbol) is
1683 a range expression, which represents the set of the two characters and
1684 all characters between the two in the collation order. A collation
1685 order is an order of characters that is defined in the locale data.
1686 If a hyphen is followed by a closing bracket (]), the bracket is
1688 treated as the end of the bracket expression and the hyphen as a normal
1689 character.
1690 For example, the range expression 3-5 represents the set of the three
1692 characters 3, 4, and 5. The bracket expression [3-5-] therefore matches
1693 one of the four characters 3, 4, 5, and -.
1694 Collating symbols
1696 A collating symbol allows more than one character to be treated as a
1697 single character in matching. A collating symbol is made up of one or
1698 more characters enclosed by the special brackets [. and .].
1699 One or more characters that are treated as a single character in
1701 matching are called a collating element. Precisely, a bracket
1702 expression pattern represents a set of collating elements and a bracket
1703 expression matches a collating element rather than a character, but we
1704 do not differentiate them for brevity here.
1705 For example, the character combination “ch” was treated as a single
1707 character in the traditional Spanish language. If this character
1708 combination is registered as a collating element in the locale data,
1709 the bracket expression [[.ch.]df] matches one of ch, d, and f.
1710 Equivalence classes
1712 An equivalence class represents a set of characters that are considered
1713 equivalent. A equivalence class is made up of a character (or more
1714 precisely, a collating element) enclosed by the special brackets [= and
1715 =].
1716 An equivalence class represents the set of characters that consists of
1718 the character enclosed by the brackets and the characters that are in
1719 the same primary equivalence class as the enclosed character. The shell
1720 consults the locale data for the definition of equivalence classes in
1721 the current locale.
1722 For example, if the six characters a, à, á, â, ã, ä are defined to be
1724 in the same primary equivalence class, the bracket expressions [[=a=]],
1725 [[=à=]], and [[=á=]] match one of the six.
1726 Character classes
1728 A character class represents a predefined set of characters. A
1729 character class is made up of a class name enclosed by the special
1730 brackets [: and :]. The shell consults the locale data for which class
1731 a character belongs to.
1732 The following character classes can be used in all locales:
1734 [:lower:]
1736 set of lowercase letters
1737 [:upper:]
1739 set of uppercase letters
1740 [:alpha:]
1742 set of letters, including the [:lower:] and [:upper:] classes.
1743 [:digit:]
1745 set of decimal digits
1746 [:xdigit:]
1748 set of hexadecimal digits
1749 [:alnum:]
1751 set of letters and digits, including the [:alpha:] and [:digit:]
1752 classes.
1753 [:blank:]
1755 set of blank characters, not including the newline character
1756 [:space:]
1758 set of space characters, including the newline character
1759 [:punct:]
1761 set of punctuations
1762 [:print:]
1764 set of printable characters
1765 [:cntrl:]
1767 set of control characters
1768 For example, the bracket expression [[:lower:][:upper:]] matches a
1770 lower or upper case character. In addition to the classes listed above,
1771 other classes may be used depending on the definition of the current
1772 locale.
1773
1775 Redirection is a feature you can use to modify file descriptors of
1776 commands. By using redirection, you can execute commands with their
1777 standard input/output connected with files or devices other than the
1778 terminal.
1779 You can do redirection by adding redirection operators to a command
1781 (simple command or compound command) In a simple command, redirection
1782 operators may appear anywhere in the command as long as operator tokens
1783 are separated from other tokens. In a compound command, redirection
1784 operators must appear at the end of the command.
1785 Redirection operators are processed before the command body is
1787 executed. More than one redirection operator in a command are processed
1788 in the order of appearance. Redirection operators affect only the
1789 command in which they appear, except when they appear in an exec
1790 built-in without command operands. That is, file descriptors modified
1791 by redirection are restored after the command has finished.
1792 A redirection operator starts with < or >. Redirection operators
1794 starting with < affects the standard input (file descriptor 0) by
1795 default. Redirection operators starting with > affects the standard
1796 output (file descriptor 1) by default. To affect another file
1797 descriptor, you can prefix a redirection operator with a non-negative
1798 integer; the operator will affect the file descriptor specified by the
1799 integer. The integer must immediately precede the < or > without any
1800 whitespaces in between. The integer must not be quoted, either.
1801 Redirection to files
1803 The most common type of redirection is redirection to files.
1804 Redirection of input
1806 < token
1807 Redirection of output
1809 > token
1810 >| token
1812 >> token
1814 Redirection of input and output
1816 <> token
1817 The token is subject to the four expansions. It is also subject to
1819 pathname expansion if the shell is interactive. The expansion result is
1820 treated as the pathname of the file to which redirection is performed.
1821 If the pathname expansion does not result in a single pathname, it is
1822 an error.
1823 In redirection of input, the standard input is replaced with a file
1825 descriptor which is open for read-only access to the target file. If
1826 the target file cannot be opened for read-only access, it is an error.
1827 In redirection of output, the standard output is replaced with a file
1829 descriptor which is open for write-only access to the target file. If
1830 the target file cannot be opened for write-only access, it is an error.
1831 If the target file does not exist, a new empty file is created and
1832 opened. If the target file already exists, the file is opened as
1833 follows:
1834 • For the >| operator, the file is emptied when opened if it is a
1836 regular file.
1837 • For the > operator, the behavior is the same as the >| operator if
1839 the clobber option is enabled. If the option is disabled and the
1840 file is a regular file, it is treated as an error.
1841 • For the >> operator, the file is opened for appending; any output
1843 to the file descriptor is appended to the end of the file.
1844 In redirection of input and output, the standard input is replaced with
1846 a file descriptor which is open for read-and-write access to the target
1847 file. If the file does not exist, a new empty file is created and
1848 opened.
1849 Socket redirection
1851 If the pathname of the target file is of the form
1852 /dev/tcp/host/port or /dev/udp/host/port and the file cannot be
1853 opened in the usual manner, a new socket is opened for
1854 communication with the port of the host. The redirection replaces
1855 the standard input or output with the file descriptor to the
1856 socket.
1857 A stream socket is opened for the form /dev/tcp/host/port and a
1859 datagram socket for the form /dev/udp/host/port. The protocol
1860 actually used for communication is determined by the socket library
1861 the shell uses. Typically, stream sockets use TCP and datagram
1862 sockets UDP.
1863 In socket redirection, the file descriptor is both readable and
1865 writable regardless of the type of the redirection operator used.
1866 Socket redirection is yash’s extension that is not defined in
1868 POSIX. Bash as well has socket redirection as extension.
1869 Duplication of file descriptors
1871 Redirection allows duplicating or closing existing file descriptors.
1872 Duplication of file descriptor
1874 <& token
1875 >& token
1877 The token is subject to expansion as in redirection to files, but it is
1879 treated as a file descriptor rather than a pathname. Thus the expanded
1880 token must be a non-negative integer.
1881 The <& and >& operators duplicate the file descriptor specified by
1883 token to the standard input and output, respectively. (The operators
1884 can be prefixed with a non-negative integer so that the file descriptor
1885 is duplicated to a file descriptor other than the standard input or
1886 output.)
1887 If the expanded token is a single hyphen rather than a non-negative
1889 integer, the file descriptor is closed rather than duplicated. By
1890 default, the <& and >& operators close the standard input and output,
1891 respectively, but the operators can be prefixed with a non-negative
1892 integer so that another file descriptor is closed.
1893 In the POSIXly-correct mode, a file descriptor must be readable when
1895 duplicated by the <& operator and writable when duplicated by the >&
1896 operator.
1897 Here documents and here strings
1899 Here document and here string allow redirection to file descriptors
1900 that reads strings directly specified in shell commands.
1901 Here document
1903 << token
1904 <<- token
1906 Here string
1908 <<< token
1909 In a here document or here string, the standard input is replaced with
1911 a readable file descriptor. When the command reads from the file
1912 descriptor, it will read the contents of the here document/string,
1913 which is defined below.
1914 When a here document operator (<< or <<-) appears in a command, the
1916 shell reads the contents of the here document starting from the next
1917 line. The contents of here documents are not parsed nor executed as
1918 commands. The token after the operand specifies a delimiter that
1919 indicates the end of the contents. (The token is not subject to any
1920 expansion, but quotation is processed.) The contents of the here
1921 document is terminated just before the first line containing the token
1922 only. When using the <<- operator, all tab characters at the beginning
1923 of each line in the here document contents are removed and the
1924 delimiter token may be preceded by tab characters.
1925 If there are more than one here document operator on one line, the
1927 contents of the here documents are parsed in order: The contents of the
1928 first here document starts from the next line and ends before the first
1929 line containing the token that followed the first operator. Just after
1930 that line, the contents of the second here document starts, and so on.
1931 The contents of here documents are treated literally: whitespaces,
1933 tabs, etc. remain as is. The exception is that, when the token is not
1934 quoted at all:
1935 • the contents are subject to parameter expansion, command
1937 substitution, arithmetic expansion.
1938 • a backslash in the contents is treated as quotation if and only if
1940 it precedes $, `, ", or another backslash.
1941 • a backslash followed by a newline is treated as line continuation.
1943 In here string, the token after the operator is subject to expansion as
1945 in redirection to files. The expansion result becomes the contents of
1946 the here string. A newline character is automatically appended to the
1947 end of here string contents.
1948 Here string is yash’s extension that is not defined in POSIX. Other
1950 shells like bash, ksh, and zsh have the same feature.
1951 Pipeline redirection
1953 Pipeline redirection allows opening pipelines that can be used for
1954 arbitrary purposes.
1955 Pipeline redirection
1957 >>| token
1958 The token is subject to expansion as in redirection to files, but it is
1960 treated as a file descriptor rather than a pathname. Thus the expanded
1961 token must be a non-negative integer.
1962 Pipeline redirection opens a new pipeline. The standard output (or the
1964 file descriptor specified before the operator, if any) is replaced with
1965 the file descriptor open for writing to the pipeline. The file
1966 descriptor specified by token is replaced with the file descriptor open
1967 for reading from the pipeline.
1968 Pipeline redirection is yash’s extension that is not defined in POSIX.
1970 Process redirection
1972 Process redirection creates a pipeline connected to another command.
1973 Process redirection
1975 <(command...)
1976 >(command...)
1978 In process redirection, the command specified is executed in a
1980 subshell. If the process redirection is of the form <(command...), the
1981 standard output of command is connected with a pipeline to the standard
1982 input of the command the redirection is associated with. If the process
1983 redirection is of the form >(command...), the standard input of command
1984 is connected with a pipeline to the standard output of the command the
1985 redirection is associated with.
1986 Process redirection is yash’s extension that is not defined in POSIX.
1988 Bash and zsh have a feature called process substitution, which uses the
1989 same syntax as yash’s process redirection, but incompatibly differs in
1990 behavior.
1991
1993 This section describes how commands are executed.
1994 Execution of simple commands
1996 A simple command is executed as follows:
1997 1. All tokens in the simple command are expanded except for assignment
1999 and redirection tokens. If an error occurs during expansion, the
2000 execution of the simple command is aborted with a non-zero exit
2001 status.
2002 In the following steps, the first word of the expansion results is
2004 referred to as command name, and the other words as command
2005 arguments. If there is only one word of the expansion results,
2006 there are no command argument words. If there are none of the
2007 expansion results, there is no command name either.
2008 2. If the command name exists and there are any redirections specified
2010 in the command, they are processed. The word token after each
2011 redirection operator is expanded. If an error occurs during
2012 processing the redirections (including when expanding the word
2013 token), the execution of this simple command is aborted with a
2014 non-zero exit status.
2015 Note
2017 In other shells, redirections may be processed in a different
2018 step: POSIX does not specify the order in which redirections
2019 and assignments are processed when there is no command name or
2020 the name denotes a special built-in.
2021 3. Assignments specified in the command, if any, are processed. For
2023 each assignment token, the value is expanded and assigned to the
2024 specified variable. If an error occurs during assignments
2025 (including when expanding the values to be assigned), the execution
2026 of this simple command is aborted with a non-zero exit status.
2027 • If there is no command name or the name denotes a special
2029 built-in, the assignments are permanent: the assigned values
2030 remain after the command has finished (until the variable is
2031 reassigned).
2032 • Otherwise, the assignments are temporary: the assigned values
2034 only last during the execution of this simple command.
2035 The assigned variables are automatically exported when the command
2037 name is specified or the all-export option is enabled.
2038 Note
2040 In other shells, assignments may behave differently: For
2041 special built-ins and functions, assigned variables may not be
2042 exported. For functions, assigned variables may be persistent,
2043 that is, may remain even after the execution of the simple
2044 command.
2045 4. If there is no command name, the redirections are processed in a
2047 subshell, then the command execution ends. If an error occurs in
2048 the redirections, the exit status of the simple command is
2049 non-zero. If there were any command substitutions performed in the
2050 assignments, the exit status of the simple command is that of the
2051 last executed command substitution. Otherwise, the exit status is
2052 zero.
2053 5. A command to be executed is determined using the command search
2055 algorithm and the command is executed.
2056 • If the command is an external command, the command is executed
2058 by creating a new subshell and calling the “exec” system call
2059 in the subshell. The command name and arguments are passed to
2060 the executed command. Exported variables are passed to the
2061 executed command as environment variables.
2062 • If the command is a built-in, the built-in is executed with the
2064 command arguments passed to the built-in.
2065 • If the command is a function, the contents of the function are
2067 executed with the command arguments as function arguments.
2068 If the command was executed, the exit status of this simple command
2070 is that of the executed command. If the algorithm failed to
2071 determine a command, no command is executed and the exit status is
2072 127. If the shell failed to execute the determined command, the
2073 exit status is 126. If the executed command was killed by a signal,
2074 the exit status is the signal number plus 384.
2075 Note
2077 In shells other than yash, the exit status may be different
2078 when the command was killed by a signal, because the POSIX
2079 standard only requires that the exit status be "greater than
2080 128."
2081 If the shell is not in the POSIXly-correct mode and the algorithm
2082 failed to determine a command, the command eval -i --
2083 "${COMMAND_NOT_FOUND_HANDLER-}" is evaluated. During the command
2084 execution, positional parameters are temporarily set to the command
2085 name and arguments that resulted in the first step. Any local
2086 variables defined during the execution are removed when the
2087 execution is finished. The HANDLED local variable is automatically
2088 defined with the initial value being the empty string. If the
2089 HANDLED variable has a non-empty value when the execution of the
2090 command string is finished, the shell pretends that the command was
2091 successfully determined and executed. The exit status of the simple
2092 command is that of the command string in this case.
2093 Command search
2095 A command that is executed in a simple command is determined by the
2096 command name using the following algorithm:
2097 1. If the command name contains a slash (/), the whole name is
2099 treated as the pathname of an external command. The external
2100 command is determined as the executed command.
2101 2. If the command name is a special built-in, the built-in is
2103 determined as the executed command.
2104 3. If the command name is the name of an existing function, the
2106 function is determined as the executed command.
2107 4. If the command name is a semi-special built-in, the built-in is
2109 determined as the executed command.
2110 5. If the command name is a regular built-in, the built-in is
2112 determined as the executed command unless the shell is in the
2113 POSIXly-correct mode.
2114 6. The shell searches the PATH for a executed command:
2116 The value of the PATH variable is separated by colons. Each
2118 separated part is considered as a directory pathname (an empty
2119 pathname denotes the current working directory). The shell
2120 searches the directories (in the order of appearance) and
2121 checks if any directory directly contains an executable regular
2122 file whose name is equal to the command name. If such a file is
2123 found:
2124 • If the command name is the name of a built-in, the built-in
2126 is determined as the executed command.
2127 • Otherwise, the file is determined as the executed command.
2129 (The file will be executed as an external command.)
2130 If no such file is found, no command is determined as the
2132 executed command.
2133 When the shell finds a file that matches the command name during
2135 the search above, the shell remembers the pathname of the file if
2136 it is an absolute path. When the algorithm above is used for the
2137 same command name again, the shell skips searching and directly
2138 determines the command to be executed. If an executable regular
2139 file no longer exists at the remembered pathname, however, the
2140 shell searches again to update the remembered pathname. You can
2141 manage remembered pathnames using the hash built-in.
2142 Termination of the shell
2144 The shell exits when it reached the end of input and has parsed and
2145 executed all input commands or when the exit built-in is executed. The
2146 exit status of the shell is that of the last command the shell executed
2147 (or zero if no commands were executed). The exit status of the shell is
2148 always between 0 and 255 (inclusive). If the exit status of the last
2149 command is 256 or larger, the exit status of the shell will be the
2150 remainder of the exit status divided by 256.
2151 If an exit handler has been registered by the trap built-in, the
2153 handler is executed just before the shell exits. The exit status of the
2154 commands executed in the handler does not affect the exit status of the
2155 shell.
2156 If a non-interactive shell encountered one of the following errors, the
2158 shell immediately exits with a non-zero exit status:
2159 • A command cannot be parsed due to an syntax error (except during
2161 shell initialization).
2162 • An error occurs during execution of a special built-in in the
2164 POSIXly-correct mode.
2165 • A redirection error occurs in a simple command whose command name
2167 is a special built-in and the shell is in the POSIXly-correct mode.
2168 • An assignment error occurs in a simple command.
2170 • An error occurs during expansion (except during shell
2172 initialization).
2173 Note
2175 Some shells other than yash exit when they fail to find a command
2176 to execute in command search.
2177 Functions
2179 Functions allow executing a compound command as a simple command. A
2180 function can be defined by the function definition command and executed
2181 by a simple command. You can use the unset built-in to remove function
2182 definitions.
2183 There are no functions predefined when yash is started.
2185 A function is executed by executing its body, which is a compound
2187 command. While the function is being executed, positional parameters
2188 are set to the arguments given to the function. The old positional
2189 parameters are restored when the function execution finishes.
2190 Local variables
2192 Local variables are temporary variables that are defined in a
2193 function and exist during the function execution only. They can be
2194 defined by the typeset built-in or implicitly created by a for
2195 loop. They are removed when the function execution finishes.
2196 Local variables may hide variables that have already been defined
2198 before the function execution had started. An existing variable
2199 becomes inaccessible if a local variable of the same name is
2200 defined in a function. The old variable becomes accessible again
2201 when the function execution finishes.
2202 You cannot create a local variable when not executing a function. A
2204 normal variable is created if you try to do so.
2205 Command execution environment
2207 The shell holds following properties during execution.
2208 • The working directory
2210 • Open file descriptors
2212 • The file creation mask (umask)
2214 • The set of signals whose handler is set to “ignore” (trap)
2216 • Environment variables
2218 • Resource limits (ulimit)
2220 Those properties are inherited from the invoker of the shell to the
2222 shell, and from the shell to each external command executed by the
2223 shell.
2224 The properties can be changed during the execution of the shell by
2226 built-in commands, variable assignments, etc.
2227 Subshells
2229 A subshell is a copy of the shell process. Subshells are used in
2230 execution of groupings, pipelines, etc.
2231 Subshells inherit functions, aliases, etc. defined in the shell as
2233 well as the properties above since subshells are copies of the
2234 shell process. Notable exceptions are:
2235 • Traps registered by the trap built-in are all reset in
2237 subshells except for ones whose action is set to “ignore”. (See
2238 below)
2239 • The interactive mode and job control are disabled in subshells.
2241 Jobs are not inherited by subshells.
2242 Subshells are executed independently of the original shell, so
2244 changes of any properties above do not affect those of the original
2245 shell.
2246 Note
2248 If the subshell contains a single trap built-in, some shells
2249 (but not yash) may not reset the traps on entry to the
2250 subshell.
2251
2253 The interactive mode is a mode of the shell intended for direct
2254 interaction with a user. If yash is in the interactive mode, it is
2255 called an interactive shell.
2256 Whether a shell runs in the interactive mode or not is determined in
2258 the invocation of the shell. After the shell has started up, the
2259 interactive mode cannot be switched on or off.
2260 When the shell is interactive:
2262 • Initialization scripts are executed during invocation.
2264 • The shell checks for mail and prints a command prompt when it reads
2266 a command. Job status changes are also reported if job control is
2267 active. Line-editing may be used depending on the capability of
2268 the terminal.
2269 • Commands executed are automatically registered in command history.
2271 • If a command executed by the shell is killed by a signal other than
2273 SIGINT and SIGPIPE, the shell reports the fact to the standard
2274 error.
2275 • The filename token is subject to pathname expansion in file
2277 redirection.
2278 • The shell does not exit when it encounters a syntax or expansion
2280 error during command execution. (cf. Termination of the shell)
2281 • The shell does not exit when it receives the SIGINT, SIGTERM, or
2283 SIGQUIT signal.
2284 • A signal handler can be changed by the trap built-in even if the
2286 handler had been set to “ignore” when the shell was invoked.
2287 • The value of the - special parameter contains i.
2289 • The shell’s locale reflects the value of the LC_CTYPE variable
2291 whenever the value is changed (if the shell is not in the
2292 POSIXly-correct mode).
2293 • Commands are executed even when the exec option is off.
2295 • The ignore-eof option takes effect when enabled.
2297 • When the shell reaches the end of input or the exit built-in is
2299 executed, the shell checks if there is any stopped job. If so, the
2300 shell prints a warning and does not actually exit.
2301 • The suspend built-in by default cannot stop the shell if it is a
2303 session leader.
2304 • The shell does not exit when the dot built-in fails to find a
2306 script file to read.
2307 • The shell does not exit when the exec built-in fails to execute a
2309 command (if not in the POSIXly-correct mode).
2310 • When a job finished for which the wait built-in has been waiting,
2312 the fact is reported (only if job control is active and not in the
2313 POSIXly-correct mode).
2314 • A prompt is printed when the read built-in reads a second or
2316 following line.
2317 Prompts
2319 The interactive shell prints a prompt just before it reads a command.
2320 The contents of the prompt is specified by the value of the PS1 and PS2
2321 variables. The former is used for reading the first line of the command
2322 and the latter for other lines.
2323 When the prompt is printed, the variable value is subjected to
2325 parameter expansion, command substitution, and arithmetic expansion
2326 (but note that the POSIX standard requires parameter expansion only).
2327 The result of the expansion is parsed by the rules below to make the
2328 actual prompt string, which is printed to the standard error.
2329 In the POSIXly-correct mode, each exclamation mark (!) in the string is
2331 substituted with the command history number of the command that is
2332 being input. Two adjacent exclamation marks (!!) are printed as a
2333 single exclamation. Other characters are printed intact.
2334 If the shell is not in the POSIXly-command mode, the following
2336 notations can be used to format the prompt string. Notations are
2337 replaced with the strings designated in the list below. Characters that
2338 are not interpreted as notations are printed intact.
2339 \a
2341 Bell character (ASCII code: 7)
2342 \e
2344 Escape character (ASCII code: 27)
2345 \j
2347 The number of jobs in the shell.
2348 \n
2350 Newline character (ASCII code: 10)
2351 \r
2353 Carriage return character (ASCII code: 13)
2354 \!
2356 The command history number of the command that is being input
2357 \$
2359 # if the shell’s effective user ID is 0; $ otherwise.
2360 \\
2362 Backslash
2363 \[, \]
2365 These two notations can surround part of the prompt string that is
2366 not visible on the terminal. The surrounded part is ignored when
2367 the shell counts the number of characters that is displayed on the
2368 terminal, thus making characters correctly aligned on the terminal
2369 when the prompt string contains special invisible characters.
2370 \ffontspecs.
2372 When line-editing is active, this notation is replaced with special
2373 characters to change font styles on the terminal if the terminal is
2374 capable of it. If line-editing is inactive or the terminal is
2375 incapable of changing font styles, this notation is silently
2376 ignored. One or more of the following can be used for fontspecs:
2377 k
2379 Change font color to black
2380 r
2382 Change font color to red
2383 g
2385 Change font color to green
2386 y
2388 Change font color to yellow
2389 b
2391 Change font color to blue
2392 m
2394 Change font color to magenta
2395 c
2397 Change font color to cyan
2398 w
2400 Change font color to white
2401 K
2403 Change background color to black
2404 R
2406 Change background color to red
2407 G
2409 Change background color to green
2410 Y
2412 Change background color to yellow
2413 B
2415 Change background color to blue
2416 M
2418 Change background color to magenta
2419 C
2421 Change background color to cyan
2422 W
2424 Change background color to white
2425 t
2427 Make font color or background brighter (can only be used just
2428 after one of the characters above)
2429 d
2431 Change font and background colors to normal
2432 s
2434 Make font standout
2435 u
2437 Make font underlined
2438 v
2440 Make font and background colors reversed
2441 b
2443 Make font blink
2444 i
2446 Make font dim
2447 o
2449 Make font bold
2450 x
2452 Make font invisible
2453 D
2455 Make color and style normal
2456 The actual colors of font and background are defined by the
2458 terminal. Different terminals may use different colors.
2459 In addition to the normal prompt, a prompt string can be displayed to
2461 the right of the cursor if line-editing is active. Those prompts are
2462 called right prompts. The contents of right prompts are defined by the
2463 value of the PS1R and PS2R variables, each corresponding to the PS1 and
2464 PS2 variables.
2465 Using the above-said notations, the font style of command strings the
2467 user inputs can be changed as well as that of prompts. The font style
2468 of command strings is defined by the value of the PS1S and PS2S
2469 variables, each corresponding to the PS1 and PS2 variables. The value
2470 can contain the \ffontspecs. notation only.
2471 When the shell is not in the POSIXly-correct mode, the prompt variables
2473 can be defined with a name prefixed with YASH_ (e.g. YASH_PS1). This
2474 allows using a different prompt string than that in the POSIXly-correct
2475 mode.
2476 When the shell is not in the POSIXly-correct mode, the value of the
2478 PROMPT_COMMAND variable is executed before each prompt.
2479 Command history
2481 Command history is a feature of the shell that remembers executed
2482 commands to allow re-executing them later. Commands executed in the
2483 interactive mode are automatically saved in the command history. Saved
2484 commands can be edited and re-executed using line-editing and the fc
2485 and history built-ins.
2486 Commands are saved line by line. Lines that do not contain any
2488 non-whitespace characters are not saved in the history. Lines that
2489 start with whitespaces are not saved when the hist-space option is on.
2490 Command history is saved in a file. When history is first used after an
2492 interactive shell was started, the shell opens a file to save history
2493 in. The filename is specified by the value of the HISTFILE variable. If
2494 the file contains history data when opened, the data is restored to the
2495 shell’s history. The file contents are updated in real time as the user
2496 inputs commands into the shell. If the HISTFILE variable is not set or
2497 the file cannot be opened successfully, history is not saved in the
2498 file, but the history feature will be functional in all other respects.
2499 The number of commands saved in history is specified by the value of
2501 the HISTSIZE variable. The shell automatically removes old history data
2502 so that the number of saved commands does not exceed the value. If the
2503 HISTSIZE variable is not set or its value is not a natural number, 500
2504 items will be saved in history.
2505 The shell looks at the value of the HISTFILE and HISTSIZE variables
2507 only when the history feature is first used after the shell was
2508 started. “The history feature is used” when:
2509 • the fc or history built-in is executed,
2511 • line-editing is used (regardless of whether or not history data is
2513 recalled in line-editing), or
2514 • a command is input to the shell
2516 Therefore, the variables should be set in initialization scripts.
2518 When more than one instance of yash shares a single history file, all
2520 the shells use the same history data. As a result, commands that have
2521 been executed by a shell instance can be recalled on another shell
2522 instance. Shells sharing the same history should have the same HISTSIZE
2523 value so that they manipulate history data properly.
2524 Yash’s history data file has its own format that is incompatible with
2526 other kinds of shells.
2527 The HISTRMDUP variable can be set to remove duplicate history items.
2529 Mail checking
2531 An interactive shell can notify receipt of email. The shell
2532 periodically checks the modification date/time of a file specified by
2533 the user. If the file has been modified since the previous check, the
2534 shell prints a notification message (except when the shell is not in
2535 the POSIXly-correct mode and the file is empty). By specifying a
2536 mailbox file to be checked, the shell will print a message when the
2537 file has been modified, that is, some mail has been received.
2538 Check is done just before the shell prints a command line prompt. The
2540 interval of checks can be specified by the MAILCHECK variable in
2541 seconds. If the variable value is 0, check is done before every prompt.
2542 If the variable value is not a non-negative integer, no checks are
2543 done.
2544 The file whose modification time is checked is specified by the MAIL
2546 variable. The variable value should be set to the pathname of the file.
2547 If you want to check more than one file or customize the notification
2549 message, you can set the MAILPATH variable instead of the MAIL
2550 variable. When the MAILPATH variable is set, the MAIL variable is
2551 ignored. The value of the MAILPATH variable should be set to one or
2552 more colon-separated pathnames of files to be checked. Each pathname
2553 can be followed by a percent sign (%) and a custom notification
2554 message, which is printed when the corresponding file has been
2555 modified. If the pathname contains a percent sign, it should be quoted
2556 by a backslash. The specified message is subject to parameter
2557 expansion. For example, if the value of the MAILPATH variable is
2558 /foo/mail%New mail!:/bar/mailbox%You've got mail:/baz/mail\%data, the
2559 shell will print
2560 • New mail! when the file /foo/mail has been modified
2562 • You've got mail when the file /bar/mailbox has been modified
2564 • the default message when the file /baz/mail%data has been modified.
2566
2568 Job control is a function of the shell that executes multiple commands
2569 simultaneously and suspends/resumes the commands.
2570 When job control is active:
2572 • Every pipeline executed by the shell becomes a job. A job has its
2574 unique process group ID that is shared among all processes in the
2575 job.
2576 • If the processes of a job are suspended while the shell is waiting
2578 for the processes to finish, the shell continues to the next
2579 command as if the process have finished. The shell remembers the
2580 job as suspended so that it can be resumed later.
2581 • If a job is executed synchronously, the shell sets the foreground
2583 process group of the terminal to the process group of the job. When
2584 the job is finished (or suspended), the shell gets back to the
2585 foreground.
2586 • The subshell executing a command substitution has its own unique
2588 process group ID like a job. However, the shell does not remember
2589 the subshell as a job, so it cannot be suspended or resumed.
2590 • If the shell is interactive, job status is reported before every
2592 command line prompt as if the command jobs -n is executed.
2593 • The standard input of an asynchronous command is not automatically
2595 redirected to /dev/null.
2596 • The shell does not exit when it receives the SIGTSTP signal.
2598 • The value of the - special parameter contains m.
2600 • When a job finished for which the wait built-in has been waiting,
2602 the fact is reported (only if the shell is interactive and not in
2603 the POSIXly-correct mode).
2604 When job control is inactive, processes executed by the shell have the
2606 same process group ID as the shell. The shell treats asynchronous
2607 commands as an uncontrolled job.
2608 You can use the following built-ins to manipulate jobs:
2610 jobs
2612 prints existing jobs
2613 fg and bg
2615 run jobs in the foreground or background
2616 wait
2618 waits for jobs to be finished (or suspended)
2619 disown
2621 forgets jobs
2622 kill
2624 sends a signal to jobs
2625 An interactive job-controlling shell reports jobs status before every
2627 prompt by default. You can set the following options to make the shell
2628 report status at other timings:
2629 notify
2631 the shell reports immediately whenever job status changes.
2632 notify-le
2634 the shell reports immediately when job status changes while
2635 line-editing.
2636 A job is removed from the shell’s job list when:
2638 • it has finished and the jobs built-in reported it,
2640 • the wait built-in successfully waited for the job to finish, or
2642 • the disown built-in removed the job.
2644 Jobs are not removed from the list when an interactive shell
2646 automatically reports the status of jobs.
2647 Note
2649 The word “stop” is synonymous to “suspend” in the context of job
2650 control.
2651 Job ID
2653 Some built-ins use the following notation, which is called job ID, to
2654 specify a job to operate on:
2655 %, %%, %+
2657 the current job
2658 %-
2660 the previous job
2661 %n
2663 the job that has job number n, where n is a positive integer
2664 %string
2666 the job whose name begins with string
2667 %?string
2669 the job whose name contains string
2670 The current job and previous job are jobs selected by the shell
2672 according to the following rules:
2673 • When there is one or more suspended jobs, the current job is
2675 selected from them.
2676 • When there is one or more suspended jobs other than the current
2678 job, the previous job is selected from them.
2679 • The current and previous jobs are always different. When the shell
2681 has only one job, it is the current job and there is no previous
2682 job.
2683 • When the current job finished, the previous job becomes the current
2685 job.
2686 • When the current job is changed, the old current job becomes the
2688 previous job except when the old job finished.
2689 • When the foreground job is suspended, the job becomes the current
2691 job.
2692 Yash has some options to modify the rules of the current/previous job
2694 selection. (The rules above have priority over the options below.)
2695 cur-async
2697 When a new asynchronous command is started, it becomes the current
2698 job.
2699 cur-bg
2701 When a job is resumed by the bg built-in, the job becomes the
2702 current job.
2703 cur-stop
2705 When a job is suspended, it becomes the current job.
2706 The current and previous jobs are not changed as long as the rules
2708 above are met.
2709 The rules of the current/previous job selection defined in the POSIX
2711 standard are looser than yash’s rules above. Other POSIX-compliant
2712 shells may select the current and previous jobs differently.
2713
2715 Built-in commands are commands that are implemented in the shell and
2716 are executed by the shell without external programs.
2717 Types of built-in commands
2719 There are three types of built-in commands in yash: special built-in
2720 commands, semi-special built-in commands and regular built-in commands.
2721 Special built-in commands are much more important commands than others.
2723 They are executed regardless of whether the corresponding external
2724 commands exist or not. Results of variable assignments that occur in a
2725 simple command that invokes a special built-in last after the command
2726 has finished. Moreover, in the POSIXly-correct mode, a non-interactive
2727 shell immediately exits with a non-zero exit status when a redirect
2728 error, assignment error, or misuse of option or operand occurs in a
2729 special built-in command.
2730 Semi special built-in commands are the second important built-in
2732 commands. They are executed regardless of whether the corresponding
2733 external commands exist or not. In other parts they are the same as
2734 regular built-in commands.
2735 Regular built-in commands are less important built-in commands
2737 including commands that can be implemented as external commands or are
2738 not listed in POSIX. In the POSIXly-correct mode, a regular built-in is
2739 executed only when a corresponding external command is found in PATH.
2740 Syntax of command arguments
2742 In this section we explain common rules about command arguments. The
2743 built-in commands of yash follow the rules unless otherwise stated.
2744 There are two types of command arguments. One is options and the other
2746 is operands. An option is an argument that starts with a hyphen (-) and
2747 changes the way the command behaves. Some options take arguments. An
2748 operand is an argument that is not an option and specifies objects the
2749 command operates on.
2750 If you specify more than one option to a command, the order of the
2752 options are normally not significant. The order of operands, however,
2753 affects the command behavior.
2754 An option is either a single-character option or a long option. A
2756 single-character option is identified by one alphabetic character. A
2757 long option is identified by multiple alphabetic characters. The POSIX
2758 standard only prescribes single-character options, so in the
2759 POSIXly-correct mode you cannot use long options.
2760 A single-character option is composed of a hyphen followed by a letter.
2762 For example, -a is a single-character option. A single-character option
2763 that takes an argument requires the argument to be just after the
2764 option name.
2765 Example 4. The set built-in and single-character options
2767 For the set built-in, -m is a single-character option that does not
2769 take an argument and -o is one that takes an argument.
2770 • set -o errexit -m
2772 • set -oerrexit -m
2774 In these two command lines, errexit is the argument to the -o option.
2776 In the second example above, the -o option and its argument are
2778 combined into a single command line argument. The POSIX standard
2779 deprecates that style and any POSIX-conforming applications must
2780 specify options and their arguments as separate command line arguments,
2781 although yash accepts both styles.
2782 You can combine single-character options that do not take arguments
2784 into a single command line argument. For example, the three options -a,
2785 -b and -c can be combined into -abc.
2786 A long option is composed of two hyphens followed by an option name.
2788 For example, --long-option is a long option. You can omit some last
2789 characters of a long option name as long as it is not ambiguous. For
2790 example, you can use --long instead of --long-option if there is no
2791 other options beginning with --long. Like a single-character option, a
2792 long option that takes an argument requires the argument to be a
2793 command line argument just after the option name or to be specified in
2794 the same command line argument as the option name, separated by an
2795 equal sign (=).
2796 Example 5. The fc built-in and long options
2798 For the fc built-in, --quiet is a long option that does not take an
2800 argument and --editor is one that takes an argument.
2801 • fc --editor vi --quiet
2803 • fc --editor=vi --quiet
2805 In these command lines, vi is the argument to the --editor option.
2807 Arguments that are not options (nor arguments to them) are interpreted
2809 as operands. The POSIX standard requires all options should be
2810 specified before any operands. Therefore, in the POSIXly-correct mode,
2811 any arguments that come after the first operand are interpreted as
2812 operands (even if they look like options). If not in the
2813 POSIXly-correct mode, you can specify options after operand.
2814 Regardless of whether the shell is in the POSIXly-correct mode or not,
2816 an argument that is just composed of two hyphens (--) can be used as a
2817 separator between options and operands. All command line arguments
2818 after the -- separator are interpreted as operands, so you can specify
2819 operands that start with a hyphen correctly using the separator.
2820 Example 6. Options and operands to the set built-in
2822 • set -a -b -- -c -d
2824 In this example, -a and -b are options and -c and -d are operands. The
2826 -- separator itself is neither an option nor an operand.
2827 Regardless of whether the shell is in the POSIXly-correct mode or not,
2829 an argument that is just composed of a single hyphen (-) is interpreted
2830 as an operand.
2831
2833 With the line-editing feature, you can edit the command text when you
2834 input a command to an interactive shell. It not only works as a simple
2835 visual-interface editor, but also is integrated with the command
2836 history. You can recall, edit, and execute commands in the history with
2837 line-editing instead of using the fc built-in.
2838 Line-editing has two editing modes, the vi and emacs modes, which each
2840 have their own key binding settings. By switching editing modes, you
2841 can change key bindings used in line-editing. Each mode has a
2842 corresponding shell option, which determines whether the mode is
2843 currently active or not. No more than one mode can be active at a time,
2844 so the options for the other modes are automatically turned off when
2845 you turn on the option for one mode. The whole line-editing feature is
2846 deactivated when those options are off.
2847 When an interactive shell is started, the vi mode is automatically
2849 activated if the standard input and error are both connected to a
2850 terminal.
2851 Line-editing can be used only when the standard input and error are
2853 both connected to a terminal. If not, the shell silently falls back to
2854 the normal input mechanism. While line-editing is being used, the shell
2855 uses the termios interface to change I/O settings of the terminal and
2856 the terminfo interface to parse input key sequences.
2857 Shell options on line-editing
2859 The following options can be set by the set built-in to enable
2860 line-editing and choose an editing mode to activate:
2861 vi
2863 activates the vi mode.
2864 emacs
2866 activates the emacs mode.
2867 The other line-editing-related options are:
2869 le-always-rp
2871 When this options is enabled, the right prompt is always visible:
2872 when the cursor reaches the right prompt, it moves to the next line
2873 from the original position, which would otherwise be overwritten by
2874 input text.
2875 le-comp-debug
2877 When enabled, internal information is printed during completion,
2878 which will help debugging completion scripts.
2879 le-conv-meta
2881 When enabled, the 8th bit of each input byte is always treated as a
2882 meta-key flag, regardless of terminfo data.
2883 le-no-conv-meta
2885 When enabled, the 8th bit of each input byte is never treated as a
2886 meta-key flag, regardless of terminfo data.
2887 The le-conv-meta and le-no-conv-meta options cannot be both enabled
2889 at a time. When either is enabled, the other is automatically
2890 disabled. When neither is enabled, the 8th bit may be treated as a
2891 meta-key flag depending on terminfo data.
2892 le-predict
2894 activates command line prediction.
2895 le-predict-empty
2897 When enabled, and command line prediction is active, suggestions
2898 are also provided for empty input lines.
2899 le-prompt-sp
2901 When enabled, the shell prints a special character sequence before
2902 printing each prompt so that every prompt is printed at the
2903 beginning of a line.
2904 This option is enabled by default.
2906 le-visible-bell
2908 When enabled, the shell flashes the terminal instead of sounding an
2909 alarm when an alert is required.
2910 Editing modes
2912 The vi mode is an editing mode that offers key bindings similar to that
2913 of the vi editor. The vi mode has two sub-modes that are switched
2914 during editing: the insert and command modes. The sub-mode is always
2915 reset to the insert mode when line-editing is started for a new command
2916 line. In the insert mode, most characters are inserted to the buffer as
2917 typed. In the command mode, input characters are treated as commands
2918 that move the cursor, insert/delete text, etc.
2919 The emacs mode offers key bindings similar to the emacs editor. Most
2921 characters are inserted to the buffer as typed, but more characters are
2922 treated as commands than the vi insert mode.
2923 Another sub-mode is used while you enter search keywords. The sub-mode
2925 is called the search mode, which offers slightly different key bindings
2926 depending on the active editing mode.
2927 Line-editing commands
2929 All characters the user enters while line-editing is active are treated
2930 as line-editing commands listed below. The bindkey built-in allows
2931 customizing the key bindings of each mode (except for the search mode).
2932 The list below shows not only the functions of commands but also the
2934 default key bindings. The keywords “vi-insert”, “vi-command”,
2935 “vi-search”, “emacs”, “emacs-search” means the vi insert mode, the vi
2936 command mode, the search mode for the vi mode (the vi search mode), the
2937 emacs mode, and the search mode for the emacs mode (the emacs search
2938 mode), respectively.
2939 Some commands take an argument that affects the function of the
2941 commands. For example, the forward-char command moves the cursor by as
2942 many characters as specified by the argument. To specify an argument,
2943 use the digit-argument command just before another command that takes
2944 an argument.
2945 Basic editing commands
2947 noop
2948 Do nothing.
2949 vi-command
2951 \^[
2952 alert
2954 Alert.
2955 self-insert
2957 Insert the input character at the current cursor position.
2958 Characters escaped by escape sequences cannot be inserted.
2959 vi-insert, emacs
2961 \\
2962 insert-tab
2964 Insert a tab character at the current cursor position.
2965 emacs
2967 \^[\^I
2968 expect-verbatim
2970 Insert a character that is entered just after this command at
2971 the current cursor position. This command can input a character
2972 that cannot be input by the self-insert command, except a null
2973 character ('\0').
2974 vi-insert, vi-search, emacs-search
2976 \^V
2977 emacs
2979 \^Q, \^V
2980 digit-argument
2982 Pass the input digit to the next command as an argument.
2983 This command can be bound to a digit or hyphen. To pass “12” as
2985 an argument to the forward-char command in the vi mode, for
2986 example, enter 12l.
2987 vi-command
2989 1, 2, 3, 4, 5, 6, 7, 8, 9
2990 emacs
2992 \^[0, \^[1, \^[2, \^[3, \^[4, \^[5, \^[6, \^[7, \^[8, \^[9,
2993 \^[-,
2994 bol-or-digit
2996 Like the beginning-of-line command if there is no argument;
2997 like the digit-argument command otherwise.
2998 vi-command
3000 0
3001 accept-line
3003 Finish editing the current line. A newline is automatically
3004 appended to the line. The line will be executed by the shell.
3005 If command line prediction is active, the current prediction
3007 (if any) is ignored. See also the accept-prediction command.
3008 vi-insert, vi-command, emacs, emacs-search
3010 \^J, \^M
3011 abort-line
3013 Abandon the current buffer and finish editing as if an empty
3014 line was input.
3015 vi-insert, vi-command, vi-search, emacs, emacs-search
3017 \!, \^C
3018 eof
3020 Abandon the current buffer and finish editing as if the shell
3021 reached the end of input. This normally makes the shell exit.
3022 eof-if-empty
3024 Like the eof command if the buffer is empty; like the alert
3025 command otherwise.
3026 vi-insert, vi-command
3028 \#, \^D
3029 eof-or-delete
3031 Like the eof command if the buffer is empty; like the
3032 delete-char command otherwise.
3033 emacs
3035 \#, \^D
3036 accept-with-hash
3038 If the current line does not begin with a hash sign (#) or
3039 there is no argument specified for this command, a hash sign is
3040 inserted at the beginning of the line. Otherwise, the beginning
3041 hash sign is removed from the line. Finally, the line is
3042 accepted like the accept-line command.
3043 vi-command
3045 #
3046 emacs
3048 \^[#
3049 accept-prediction
3051 Like the accept-line command, but include the predicted part.
3052 setmode-viinsert
3054 Switch to the vi insert mode.
3055 vi-command
3057 i, \I
3058 setmode-vicommand
3060 Switch to the vi command mode.
3061 vi-insert
3063 \^[
3064 setmode-emacs
3066 Switch to the emacs mode.
3067 expect-char, abort-expect-char
3069 These commands are not meant for use by the user. They are used
3070 by the shell to implement some other commands.
3071 redraw-all
3073 Reprint the prompt and the current line to the terminal.
3074 vi-insert, vi-command, vi-search, emacs, emacs-search
3076 \^L
3077 clear-and-redraw-all
3079 Clear the terminal and reprint the prompt and the current line.
3080 Motion commands
3082 Motion commands move the cursor on the line. Most motion commands
3083 accept an argument. When passed an argument, they repeat the cursor
3084 motion as many times as specified by the argument. Passing “4” as
3085 an argument to the forward-char command, for example, advances the
3086 cursor by four characters.
3087 The shell has several definitions of words as units of distance: A
3089 bigword is one or more adjacent non-whitespace characters. A
3090 semiword is one or more adjacent characters that contain no
3091 whitespaces or punctuations. An emacsword is one or more adjacent
3092 alphanumeric characters. A viword is either:
3093 • one or more adjacent alphanumeric characters and/or underscores
3095 (_), or
3096 • one or more adjacent characters that contain none of
3098 alphanumeric characters, underscores, and whitespaces.
3099 forward-char
3101 Move the cursor to the next character.
3102 vi-insert
3104 \R
3105 vi-command
3107 l, (space), \R
3108 emacs
3110 \R, \^F
3111 backward-char
3113 Move the cursor to the previous character.
3114 vi-insert
3116 \L
3117 vi-command
3119 h, \B, \L, \?, \^H
3120 emacs
3122 \L, \^B
3123 forward-bigword
3125 Move the cursor to the next bigword.
3126 vi-command
3128 W
3129 end-of-bigword
3131 Move the cursor to the next end of a bigword.
3132 vi-command
3134 E
3135 backward-bigword
3137 Move the cursor to the previous bigword.
3138 vi-command
3140 B
3141 forward-semiword
3143 Move the cursor to the next semiword.
3144 end-of-semiword
3146 Move the cursor to the next end of a semiword.
3147 backward-semiword
3149 Move the cursor to the previous semiword.
3150 forward-viword
3152 Move the cursor to the next viword.
3153 vi-command
3155 w
3156 end-of-viword
3158 Move the cursor to the next end of a viword.
3159 vi-command
3161 e
3162 backward-viword
3164 Move the cursor to the previous viword.
3165 vi-command
3167 b
3168 forward-emacsword
3170 Move the cursor to the next emacsword.
3171 emacs
3173 \^[f, \^[F
3174 backward-emacsword
3176 Move the cursor to the previous emacsword.
3177 emacs
3179 \^[b, \^[B
3180 beginning-of-line
3182 Move the cursor to the beginning of the line.
3183 vi-insert, vi-command
3185 \H
3186 emacs
3188 \H, \^A
3189 end-of-line
3191 Move the cursor to the end of the line.
3192 vi-insert
3194 \E
3195 vi-command
3197 $, \E
3198 emacs
3200 \E, \^E
3201 go-to-column
3203 Move the cursor to the nth character on the line, where n is
3204 the argument. Assume n = 1 when no argument.
3205 vi-command
3207 |
3208 first-nonblank
3210 Move the cursor to the first non-blank character on the line.
3211 vi-command
3213 ^
3214 find-char
3216 Move the cursor to the first position where a character that is
3217 entered just after this command appears after the current
3218 cursor position.
3219 vi-command
3221 f
3222 emacs
3224 \^]
3225 find-char-rev
3227 Move the cursor to the last position where a character that is
3228 entered just after this command appears before the current
3229 cursor position.
3230 vi-command
3232 F
3233 emacs
3235 \^[\^]
3236 till-char
3238 Move the cursor to the first position just before a character
3239 that is entered just after this command appears after the
3240 current cursor position.
3241 vi-command
3243 t
3244 till-char-rev
3246 Move the cursor to the last position just after a character
3247 that is entered just after this command appears before the
3248 current cursor position.
3249 vi-command
3251 T
3252 refind-char
3254 Redo the last find-char, find-char-rev, till-char,
3255 till-char-rev command.
3256 vi-command
3258 ;
3259 refind-char-rev
3261 Redo the last find-char, find-char-rev, till-char,
3262 till-char-rev command in the reverse direction.
3263 vi-command
3265 ,
3266 Editing commands
3268 Editing commands modify contents of the buffer. Most editing
3269 commands accept an argument. When passed an argument, they repeat
3270 the modification as many times as specified by the argument.
3271 Texts deleted by commands whose name starts with “kill” are saved
3273 in kill ring, from which deleted contents can be restored to the
3274 buffer. The most recent 32 texts are kept in the kill ring.
3275 delete-char
3277 Delete a character at the current cursor position if no
3278 argument is passed; like the kill-char command otherwise.
3279 vi-insert, emacs
3281 \X
3282 delete-bigword
3284 Delete a bigword at the current cursor position if no argument
3285 is passed; like the kill-bigword command otherwise.
3286 delete-semiword
3288 Delete a semiword at the current cursor position if no argument
3289 is passed; like the kill-semiword command otherwise.
3290 delete-viword
3292 Delete a viword at the current cursor position if no argument
3293 is passed; like the kill-viword command otherwise.
3294 delete-emacsword
3296 Delete a emacsword at the current cursor position if no
3297 argument is passed; like the kill-emacsword command otherwise.
3298 backward-delete-char
3300 Delete a character just before the current cursor position if
3301 no argument is passed; like the backward-kill-char command
3302 otherwise.
3303 vi-insert, emacs
3305 \B, \?, \^H
3306 backward-delete-bigword
3308 Delete a bigword just before the current cursor position if no
3309 argument is passed; like the backward-kill-bigword command
3310 otherwise.
3311 backward-delete-semiword
3313 Delete a semiword just before the current cursor position if no
3314 argument is passed; like the backward-kill-semiword command
3315 otherwise.
3316 vi-insert
3318 \^W
3319 backward-delete-viword
3321 Delete a viword just before the current cursor position if no
3322 argument is passed; like the backward-kill-viword command
3323 otherwise.
3324 backward-delete-emacsword
3326 Delete a emacsword just before the current cursor position if
3327 no argument is passed; like the backward-kill-emacsword command
3328 otherwise.
3329 delete-line
3331 Delete the whole buffer contents.
3332 forward-delete-line
3334 Delete all characters from the current cursor position to the
3335 end of the buffer.
3336 backward-delete-line
3338 Delete all characters before the current cursor position.
3339 vi-insert
3341 \$, \^U
3342 kill-char
3344 Delete a character at the current cursor position and add it to
3345 the kill ring.
3346 vi-command
3348 x, \X
3349 kill-bigword
3351 Delete a bigword at the current cursor position and add it to
3352 the kill ring.
3353 kill-semiword
3355 Delete a semiword at the current cursor position and add it to
3356 the kill ring.
3357 kill-viword
3359 Delete a viword at the current cursor position and add it to
3360 the kill ring.
3361 kill-emacsword
3363 Delete a emacsword at the current cursor position and add it to
3364 the kill ring.
3365 emacs
3367 \^[d, \^[D
3368 backward-kill-char
3370 Delete a character just before the current cursor position and
3371 add it to the kill ring.
3372 vi-command
3374 X
3375 backward-kill-bigword
3377 Delete a bigword just before the current cursor position and
3378 add it to the kill ring.
3379 emacs
3381 \^W
3382 backward-kill-semiword
3384 Delete a semiword just before the current cursor position and
3385 add it to the kill ring.
3386 backward-kill-viword
3388 Delete a viword just before the current cursor position and add
3389 it to the kill ring.
3390 backward-kill-emacsword
3392 Delete a emacsword just before the current cursor position and
3393 add it to the kill ring.
3394 emacs
3396 \^[\B, \^[\?, \^[\^H
3397 kill-line
3399 Delete the whole buffer contents and add it to the kill ring.
3400 forward-kill-line
3402 Delete all characters from the current cursor position to the
3403 end of the buffer and add it to the kill ring.
3404 emacs
3406 \^K
3407 backward-kill-line
3409 Delete all characters before the current cursor position and
3410 add it to the kill ring.
3411 emacs
3413 \$, \^U, \^X\B, \^X\?
3414 put-before
3416 Insert the last-killed text before the current cursor position
3417 and move the cursor to the last character that was inserted.
3418 vi-command
3420 P
3421 put
3423 Insert the last-killed text after the current cursor position
3424 and move the cursor to the last character that was inserted.
3425 vi-command
3427 p
3428 put-left
3430 Insert the last-killed text before the current cursor position
3431 and move the cursor to the last character that was inserted.
3432 emacs
3434 \^Y
3435 put-pop
3437 Replace the just put text with the next older killed text.
3438 This command can be used only just after the put-before, put,
3440 put-left, or put-pop command.
3441 emacs
3443 \^[y, \^[Y
3444 undo
3446 Cancel modification by the last editing command.
3447 vi
3449 u
3450 emacs
3452 \^_, \^X\$, \^X\^U
3453 undo-all
3455 Cancel all modification in the current buffer, restoring the
3456 initial contents.
3457 vi
3459 U
3460 emacs
3462 \^[\^R, \^[r, \^[R
3463 cancel-undo
3465 Cancel cancellation by the last undo or undo-all command.
3466 vi
3468 \^R
3469 cancel-undo-all
3471 Cancel all cancellation by all most recent undo and undo-all
3472 commands.
3473 redo
3475 Repeat modification by the last editing command.
3476 vi-command
3478 .
3479 Completion commands
3481 complete
3482 Complete a word just before the cursor position and, if there
3483 is more than one candidate, show a list of the candidates.
3484 complete-next-candidate
3486 Like the complete command when candidates are not being listed;
3487 otherwise, select the next candidate in the list.
3488 vi-insert, emacs
3490 \^I
3491 complete-prev-candidate
3493 Like the complete command when candidates are not being listed;
3494 otherwise, select the previous candidate in the list.
3495 vi-insert, emacs
3497 \bt
3498 complete-next-column
3500 Like the complete command when candidates are not being listed;
3501 otherwise, select the first candidate in the next column in the
3502 list.
3503 complete-prev-column
3505 Like the complete command when candidates are not being listed;
3506 otherwise, select the first candidate in the previous column in
3507 the list.
3508 complete-next-page
3510 Like the complete command when candidates are not being listed;
3511 otherwise, select the first candidate in the next page in the
3512 list.
3513 complete-prev-page
3515 Like the complete command when candidates are not being listed;
3516 otherwise, select the first candidate in the previous page in
3517 the list.
3518 complete-list
3520 Complete a word just before the cursor position.
3521 If you pass no argument, a list of completion candidates is
3523 shown. Otherwise, the word is completed with the nth candidate
3524 where n is the argument.
3525 emacs
3527 \^[?, \^[=
3528 complete-all
3530 Replace a word just before the cursor position with all
3531 possible completion candidates, each separated by a space.
3532 emacs
3534 \^[*
3535 complete-max
3537 Complete a word just before the cursor position with the
3538 longest prefix of all possible completion candidates.
3539 complete-max-then-list
3541 Works like the complete-max command for the first use, then
3542 like the complete command when used successively.
3543 complete-max-then-next-candidate
3545 Works like the complete-max command for the first use, then
3546 like the complete-next-candidate command when used
3547 successively.
3548 complete-max-then-prev-candidate
3550 Works like the complete-max command for the first use, then
3551 like the complete-prev-candidate command when used
3552 successively.
3553 clear-candidates
3555 Clear the list of completion candidates.
3556 Vi-specific commands
3558 vi-replace-char
3559 Replace the character at the cursor position with a character
3560 that is entered just after this command.
3561 vi-command
3563 r
3564 vi-insert-beginning
3566 Move the cursor to the beginning of the line and switch to the
3567 vi insert mode.
3568 vi-command
3570 I
3571 vi-append
3573 Move the cursor to the next character and switch to the vi
3574 insert mode.
3575 vi-command
3577 I
3578 vi-append-to-eol
3580 Move the cursor to the end of the line and switch to the vi
3581 insert mode.
3582 vi-command
3584 A
3585 vi-replace
3587 Switch to the vi insert mode and start overwriting. While
3588 overwriting, the self-insert command replaces the character at
3589 cursor position rather than inserting a character. Overwriting
3590 ends when the editing mode is changed.
3591 vi-command
3593 R
3594 vi-switch-case
3596 Switch case of characters between the current and next cursor
3597 positions. This command must be followed by a motion command,
3598 which determines the next cursor position.
3599 vi-switch-case-char
3601 Switch case of the character at the current cursor position and
3602 move the cursor to the next character.
3603 vi-command
3605 ~
3606 vi-yank
3608 Add to the kill ring the characters between the current and
3609 next cursor positions. This command must be followed by a
3610 motion command, which determines the next cursor position.
3611 vi-command
3613 y
3614 vi-yank-to-eol
3616 Add to the kill ring the characters from the current cursor
3617 position to the end of the line.
3618 vi-command
3620 Y
3621 vi-delete
3623 Delete characters between the current and next cursor positions
3624 and add it to the kill ring. This command must be followed by a
3625 motion command, which determines the next cursor position.
3626 vi-command
3628 d
3629 vi-delete-to-eol
3631 Delete the characters from the current cursor position to the
3632 end of the line and add it to the kill ring.
3633 vi-command
3635 D
3636 vi-change
3638 Delete characters between the current and next cursor positions
3639 and switch to the vi insert mode. This command must be followed
3640 by a motion command, which determines the next cursor position.
3641 vi-command
3643 c
3644 vi-change-to-eol
3646 Delete the characters from the current cursor position to the
3647 end of the line and switch to the vi insert mode.
3648 vi-command
3650 C
3651 vi-change-line
3653 Delete the whole buffer contents and switch to the vi insert
3654 mode.
3655 vi-command
3657 S
3658 vi-yank-and-change
3660 Like the vi-change command, but the deleted text is added to
3661 the kill ring.
3662 vi-yank-and-change-to-eol
3664 Like the vi-change-to-eol command, but the deleted text is
3665 added to the kill ring.
3666 vi-yank-and-change-line
3668 Like the vi-change-line command, but the deleted text is added
3669 to the kill ring.
3670 vi-substitute
3672 Delete a character at the current cursor position, add it to
3673 the kill ring, and switch to the vi insert mode.
3674 vi-command
3676 s
3677 vi-append-last-bigword
3679 Insert a space and the last bigword in the most recent command
3680 history entry just after the current cursor position and switch
3681 to the vi insert mode. If argument n is passed, the nth bigword
3682 in the entry is inserted instead of the last.
3683 vi-command
3685 _
3686 vi-exec-alias
3688 Execute the value of an alias named _c as editing commands
3689 where c is a character input just after this command.
3690 vi-command
3692 @
3693 vi-edit-and-accept
3695 Start the vi editor to edit the current buffer contents. When
3696 the editor finished, the edited buffer contents is accepted
3697 like the accept-line command unless the exit status of the
3698 editor is non-zero.
3699 vi-command
3701 v
3702 vi-complete-list
3704 Like the complete-list command, but also switch to the vi
3705 insert mode.
3706 vi-command
3708 =
3709 vi-complete-all
3711 Like the complete-all command, but also switch to the vi insert
3712 mode.
3713 vi-command
3715 *
3716 vi-complete-max
3718 Like the complete-max command, but also switch to the vi insert
3719 mode.
3720 vi-command
3722 \\
3723 vi-search-forward
3725 Switch to the vi search mode and start forward history search.
3726 vi-command
3728 ?
3729 vi-search-backward
3731 Switch to the vi search mode and start backward history search.
3732 vi-command
3734 /
3735 Emacs-specific commands
3737 emacs-transpose-chars
3738 Move a character just before the cursor to the right.
3739 emacs
3741 \^T
3742 emacs-transpose-words
3744 Move an emacsword just before the cursor to the right.
3745 emacs
3747 \^[t, \^[T
3748 emacs-downcase-word
3750 Make an emacsword just after the cursor lowercase.
3751 emacs
3753 \^[l, \^[L
3754 emacs-upcase-word
3756 Make an emacsword just after the cursor uppercase.
3757 emacs
3759 \^[u, \^[U
3760 emacs-capitalize-word
3762 Capitalize the first letter of an emacsword just after the
3763 cursor.
3764 emacs
3766 \^[c, \^[u
3767 emacs-delete-horizontal-space
3769 Delete spaces around the cursor. If any argument was passed,
3770 delete spaces just before the cursor only.
3771 emacs
3773 \^[\\
3774 emacs-just-one-space
3776 Delete spaces around the cursor and leave one space. If an
3777 argument is specified, leave as many spaces as the argument.
3778 emacs
3780 \^[ (Escape followed by a space)
3781 emacs-search-forward
3783 Switch to the emacs search mode and start forward history
3784 search.
3785 emacs
3787 \^S
3788 emacs-search-backward
3790 Switch to the emacs search mode and start backward history
3791 search.
3792 emacs
3794 \^R
3795 History-related commands
3797 oldest-history
3798 Recall the oldest entry in the history. If argument n is
3799 passed, the entry whose number is n is recalled instead. The
3800 cursor position remains unchanged.
3801 newest-history
3803 Recall the newest entry in the history. If argument n is
3804 passed, the entry whose number is n is recalled instead. The
3805 cursor position remains unchanged.
3806 return-history
3808 Return to the initial buffer corresponding to none of existing
3809 history entries. If argument n is passed, the entry whose
3810 number is n is recalled instead. The cursor position remains
3811 unchanged.
3812 oldest-history-bol
3814 Recall the oldest entry in the history and move the cursor to
3815 the beginning of the line. If argument n is passed, the entry
3816 whose number is n is recalled instead.
3817 vi-command
3819 G
3820 newest-history-bol
3822 Recall the newest entry in the history and move the cursor to
3823 the beginning of the line. If argument n is passed, the entry
3824 whose number is n is recalled instead.
3825 return-history-bol
3827 Return to the initial buffer corresponding to none of existing
3828 history entries and move the cursor to the beginning of the
3829 line. If argument n is passed, the entry whose number is n is
3830 recalled instead.
3831 vi-command
3833 g
3834 oldest-history-eol
3836 Recall the oldest entry in the history and move the cursor to
3837 the end of the line. If argument n is passed, the entry whose
3838 number is n is recalled instead.
3839 emacs
3841 \^[<
3842 newest-history-eol
3844 Recall the newest entry in the history and move the cursor to
3845 the end of the line. If argument n is passed, the entry whose
3846 number is n is recalled instead.
3847 return-history-eol
3849 Return to the initial buffer corresponding to none of existing
3850 history entries and move the cursor to the end of the line. If
3851 argument n is passed, the entry whose number is n is recalled
3852 instead.
3853 emacs
3855 \^[>
3856 next-history
3858 Recall the next history entry. The cursor position remains
3859 unchanged.
3860 prev-history
3862 Recall the previous history entry. The cursor position remains
3863 unchanged.
3864 next-history-bol
3866 Recall the next history entry and move the cursor to the
3867 beginning of the line.
3868 vi-command
3870 j, +, \D, \^N
3871 prev-history-bol
3873 Recall the previous history entry and move the cursor to the
3874 beginning of the line.
3875 vi-command
3877 k, -, \U, \^P
3878 next-history-eol
3880 Recall the next history entry and move the cursor to the end of
3881 the line.
3882 vi-insert, emacs
3884 \D, \^N
3885 prev-history-eol
3887 Recall the previous history entry and move the cursor to the
3888 end of the line.
3889 vi-insert, emacs
3891 \U, \^P
3892 search-again
3894 Repeat the last command history search.
3895 vi-command
3897 n
3898 search-again-rev
3900 Repeat the last command history search in the reverse
3901 direction.
3902 vi-command
3904 N
3905 search-again-forward
3907 Repeat the last command history search in the forward
3908 direction.
3909 search-again-backward
3911 Repeat the last command history search in the backward
3912 direction.
3913 beginning-search-forward
3915 Recall the next history entry that starts with the same text as
3916 the text from the beginning of the line up to the current
3917 cursor position. The cursor position remains unchanged.
3918 beginning-search-backward
3920 Recall the previous history entry that starts with the same
3921 text as the text from the beginning of the line up to the
3922 current cursor position. The cursor position remains unchanged.
3923 Search mode commands
3925 srch-self-insert
3926 Insert the input character at the current cursor position.
3927 Characters escaped by escape sequences cannot be inserted.
3928 vi-search, emacs-search
3930 \\
3931 srch-backward-delete-char
3933 Delete the last character in the search text. If the text is
3934 empty:
3935 • like the srch-abort-search command when in the vi search
3937 mode, or
3938 • like the alert command when in the emacs search mode.
3940 vi-search, emacs-search
3942 \B, \?, \^H
3943 srch-backward-delete-line
3945 Delete the whole search text.
3946 vi-search, emacs-search
3948 \$, \^U
3949 srch-continue-forward
3951 Find the next matching history entry.
3952 emacs-search
3954 \^S
3955 srch-continue-backward
3957 Find the previous matching history entry.
3958 emacs-search
3960 \^R
3961 srch-accept-search
3963 Finish the search mode, accepting the result being shown.
3964 vi-search
3966 \^J, \^M
3967 emacs-search
3969 \^J, \^[
3970 srch-abort-search
3972 Abort search and restore the previous buffer contents.
3973 vi-search
3975 \^[
3976 emacs-search
3978 \^G
3979 Escape sequences
3981 In the bindkey built-in, escape sequences are used to represent special
3982 keys such as function keys and arrow keys. Every escape sequence starts
3983 with a backslash (\) and thus there is also an escape sequence for a
3984 backslash itself.
3985 Below are available escape sequences:
3987 \\
3989 Backslash (\)
3990 \B
3992 Backspace
3993 \D
3995 Down arrow
3996 \E
3998 End
3999 \H
4001 Home
4002 \I
4004 Insert (Insert-char, Enter-insert-mode)
4005 \L
4007 Left arrow
4008 \N
4010 Page-down (Next-page)
4011 \P
4013 Page-up (Previous-page)
4014 \R
4016 Right arrow
4017 \U
4019 Up arrow
4020 \X
4022 Delete
4023 \!
4025 INTR
4026 \#
4028 EOF
4029 \$
4031 KILL
4032 \?
4034 ERASE
4035 \^@
4037 Ctrl + @
4038 \^A, \^B, ..., \^Z
4040 Ctrl + A, Ctrl + B, ..., Ctrl + Z
4041 Note that Ctrl + I, Ctrl + J, and Ctrl + M are tab, newline, and
4043 carriage return, respectively.
4044 \^[
4046 Ctrl + [ (Escape)
4047 \^\
4049 Ctrl + \
4050 \^]
4052 Ctrl + ]
4053 \^^
4055 Ctrl + ^
4056 \^_
4058 Ctrl + _
4059 \^?
4061 Ctrl + ? (Delete)
4062 \F00, \F01, ..., \F63
4064 F0, F1, ..., F63
4065 \a1
4067 Top-left on keypad
4068 \a3
4070 Top-right on keypad
4071 \b2
4073 Center on keypad
4074 \bg
4076 Beginning
4077 \bt
4079 Back-tab
4080 \c1
4082 Bottom-left on keypad
4083 \c3
4085 Bottom-right on keypad
4086 \ca
4088 Clear-all-tabs
4089 \cl
4091 Close
4092 \cn
4094 Cancel
4095 \co
4097 Command
4098 \cp
4100 Copy
4101 \cr
4103 Create
4104 \cs
4106 Clear-screen or erase
4107 \ct
4109 Clear-tab
4110 \dl
4112 Delete-line
4113 \ei
4115 Exit-insert-mode
4116 \el
4118 Clear-to-end-of-line
4119 \es
4121 Clear-to-end-of-screen
4122 \et
4124 Enter (Send)
4125 \ex
4127 Exit
4128 \fd
4130 Find
4131 \hp
4133 Help
4134 \il
4136 Insert-line
4137 \ll
4139 Home-down
4140 \me
4142 Message
4143 \mk
4145 Mark
4146 \ms
4148 Mouse event
4149 \mv
4151 Move
4152 \nx
4154 Next-object
4155 \on
4157 Open
4158 \op
4160 Options
4161 \pr
4163 Print (Copy)
4164 \pv
4166 Previous-object
4167 \rd
4169 Redo
4170 \re
4172 Resume
4173 \rf
4175 Ref (Reference)
4176 \rh
4178 Refresh
4179 \rp
4181 Replace
4182 \rs
4184 Restart
4185 \sf
4187 Scroll-forward (Scroll-down)
4188 \sl
4190 Select
4191 \sr
4193 Scroll-backward (Scroll-up)
4194 \st
4196 Set-tab
4197 \su
4199 Suspend
4200 \sv
4202 Save
4203 \ud
4205 Undo
4206 \SE
4208 Shift + End
4209 \SH
4211 Shift + Home
4212 \SI
4214 Shift + Insert
4215 \SL
4217 Shift + Left arrow
4218 \SR
4220 Shift + Right arrow
4221 \SX
4223 Shift + Delete
4224 \Sbg
4226 Shift + Beginning
4227 \Scn
4229 Shift + Cancel
4230 \Sco
4232 Shift + Command
4233 \Scp
4235 Shift + Copy
4236 \Scr
4238 Shift + Create
4239 \Sdl
4241 Shift + Delete-line
4242 \Sel
4244 Shift + End-of-line
4245 \Sex
4247 Shift + Exit
4248 \Sfd
4250 Shift + Find
4251 \Shp
4253 Shift + Help
4254 \Smg
4256 Shift + Message
4257 \Smv
4259 Shift + Move
4260 \Snx
4262 Shift + Next
4263 \Sop
4265 Shift + Options
4266 \Spr
4268 Shift + Print
4269 \Spv
4271 Shift + Previous
4272 \Srd
4274 Shift + Redo
4275 \Sre
4277 Shift + Resume
4278 \Srp
4280 Shift + Replace
4281 \Ssu
4283 Shift + Suspend
4284 \Ssv
4286 Shift + Save
4287 \Sud
4289 Shift + Undo
4290 INTR, EOF, KILL, and ERASE are special characters configured by the
4292 stty command. In a typical configuration, they are sent by typing
4293 Ctrl+C, Ctrl+D, Ctrl+U, and Ctrl+H, respectively, but some
4294 configuration uses Ctrl+? instead of Ctrl+H for ERASE.
4295 Command line completion
4297 By using the complete and complete-next-candidate commands, etc., you
4298 can complete command names, options, and operands. By default, the
4299 complete-next-candidate command is bound with the Tab key in the vi
4300 insert and emacs modes.
4301 Type a few first letters of a command name or pathname and hit the Tab
4303 key, and a list of matching names will be shown. You can choose a
4304 candidate from the list to complete the name by hitting the Tab key
4305 again. If there is only one matching name, no list will be shown and
4306 the name will directly be completed.
4307 If the name to be completed contains characters like * and ?, it is
4309 treated as a pattern. The name on the command line will be directly
4310 substituted with all possible names matching the pattern (you cannot
4311 choose from a list).
4312 Normally, command names are completed with command names and command
4314 arguments with pathnames. However, completion functions can be defined
4315 to refine completion results.
4316 Completion details
4318 When doing completion for the first time after the shell has been
4319 started, the INIT file is loaded as if the command string . -AL
4320 completion/INIT is executed. If the file is not found, it is
4321 silently ignored. This automatic loading is mainly intended for
4322 loading completion functions bundled with the shell, but you can
4323 let the shell load your own functions by putting a file in the load
4324 path.
4325 When completing a command name, the shell executes the
4327 completion//command function and when completing a command
4328 argument, the completion//argument function. If those completion
4329 functions are not defined, the shell just completes with command
4330 names or pathnames. When completing other names, such as the user
4331 name in tilde expansion and the parameter name in parameter
4332 expansion, completion functions are never used: the shell just
4333 completes with user names, parameter names, or whatever applicable.
4334 Completion functions are executed without any arguments. The
4336 following local variables are automatically defined while executing
4337 completion functions:
4338 IFS
4340 The value is the three characters of a space, a tab, and a
4341 newline, which are the default value of the variable.
4342 WORDS
4344 This variable is an array whose elements are a command name and
4345 arguments that have already been entered before the argument
4346 being completed. When completing a command name, the array has
4347 no elements.
4348 TARGETWORD
4350 The value is the partially entered command name or argument
4351 that is being completed.
4352 Completion candidates are generated by executing the complete
4354 built-in during a completion function.
4355 Completion functions must not perform I/O to the terminal, or
4357 displayed text will be corrupted. Completion functions should run
4358 as quickly as possible for better user experience.
4359 While a completion function is being executed:
4361 • the POSIXly-correct mode and the err-return option are
4363 temporarily disabled,
4364 • the err-exit option is temporarily ignored, and
4366 • traps are not executed.
4368 Command line prediction
4370 This is an experimental feature. When the le-predict option is enabled,
4371 the shell automatically tries to predict a command string fragment that
4372 follows the part of the command you have already typed in line-editing.
4373 For example, assume you have once typed the command ls Documents. Next
4375 time you start typing ls Doc, the shell will show uments just after the
4376 cursor. If you are satisfied with this suggestion, you can move the
4377 cursor to the right by the forward-char or any other motion commands
4378 instead of typing the rest of the command. After moving the cursor
4379 after the last s, you can use the accept-line command to execute the
4380 command. You can also use the accept-prediction command to immediately
4381 execute the suggested command without moving the cursor.
4382 To distinguish the typed part and the predicted part of a command
4384 string, you can change the font style of the typed part by setting the
4385 PS1S variable. Customizing the font style of the predicted part is not
4386 (yet) supported; it is always shown in the default style.
4387 When you move the cursor to the right, the predicted part up to the
4389 cursor becomes the typed part as if you actually typed it. Moving the
4390 cursor to the left does not turn the typed part back to the prediction.
4391 Use deletion commands such as backward-delete-char to delete typed
4392 command fragment.
4393 The predicted part of the command is shown only when the cursor is at
4395 the end of the typed part.
4396 By default, the predicted part is shown after you start typing a
4398 command string. By enabling the le-predict-empty option, the predicted
4399 part is also shown before you type the first character of the command
4400 string.
4401 The prediction algorithm suggests command fragments on the basis of the
4403 command history. The algorithm considers recent history entries more
4404 probable. It also takes command succession patterns into account. A
4405 predicted command fragment is not always a complete valid command
4406 because less probable part of the fragment is excluded from prediction.
4407
4409 Yash behaves as defined in POSIX.1-2008, Shell & Utilities for the most
4410 part, but some functionalities disobey POSIX for usability. When full
4411 POSIX-conformance is needed, you can enable the POSIXly-correct mode to
4412 make yash obey POSIX as much as possible.
4413 If yash is started with the name “sh”, the POSIXly-correct mode is
4415 automatically enabled. The -o posixly-correct command-line option also
4416 enables the POSIXly-correct mode. After yash has been started, the
4417 POSIXly-correct mode can be enabled by executing the command string set
4418 -o posixly-correct.
4419 When the POSIXly-correct mode is on, yash not only tries to obey the
4421 requirements by POSIX, but also treats as errors most conditions where
4422 the behavior is undefined or unspecified by POSIX. As a result, most
4423 yash-specific functionalities are disabled in the POSIXly-correct mode.
4424 Below is the complete list of the behavioral differences between when
4426 yash is in the POSIXly-correct mode and when not. When the
4427 POSIXly-correct mode is enabled:
4428 • Different initialization scripts are used.
4430 • If the shell was started with the -c option, sh -c (instead of yash
4432 -c) is printed as the script pathname on a syntax error.
4433 • Global aliases are not substituted.
4435 • Nested commands in a compound command must not be empty.
4437 • The for loop iteration variable is created as global, regardless of
4439 the for-local shell option. The variable must have a portable
4440 (ASCII-only) name.
4441 • The first pattern in a case command cannot be esac.
4443 • The ! keyword cannot be followed by ( without any whitespaces
4445 in-between.
4446 • The double-bracket command cannot be used.
4448 • The function keyword cannot be used for function definition. The
4450 function must have a portable (ASCII-only) name.
4451 • Simple commands cannot assign to arrays.
4453 • Changing the value of the LC_CTYPE variable after the shell has
4455 been initialized does not affect the shell’s locale.
4456 • The RANDOM variable cannot be used to generate random numbers.
4458 • Tilde expansion only expands ~ and ~username.
4460 • Parameter expansion cannot be nested. No indexes or modifiers with
4462 word2 are allowed.
4463 • The commands in a command substitution of the form $(commands) are
4465 parsed every time the substitution is executed.
4466 • In arithmetic expansion, fractional numbers and the ++ and --
4468 operators cannot be used. All variables must be numeric.
4469 • The operand of a redirection cannot be the integer prefix to a next
4471 redirection operator.
4472 • A compound command with a redirection cannot be immediately
4474 followed by a keyword like } and fi.
4475 • In a redirection to a file, if the pathname expansion yielded more
4477 than one or no pathname, it is not immediately treated as an error.
4478 Instead, the shell tries to treat the word before the expansion as
4479 a pathname.
4480 • A file descriptor must be readable and writable when duplicated by
4482 the <& and >& redirection operator, respectively.
4483 • Socket redirection, here strings, pipe redirection, and process
4485 redirection cannot be used.
4486 • When executing a simple command, failure in command search does not
4488 trigger execution of the COMMAND_NOT_FOUND_HANDLER variable.
4489 • In command search, a regular built-in needs to have a corresponding
4491 external command for the built-in to be found.
4492 • Some built-ins behave differently. Especially, long command-line
4494 options (as well as some others) cannot be used.
4495 • A non-interactive shell exits when a special built-in is given a
4497 syntactically wrong arguments or when an error occurs in assignment
4498 or redirection with a special built-in.
4499 • An interactive shell does not execute the PROMPT_COMMAND variable
4501 before printing a prompt. The values of the PS1, PS2, and PS4
4502 variables are parsed differently. Prompt variables with a YASH_
4503 prefix (e.g. YASH_PS1) are not used.
4504 • In mail checking, a notification message is printed if the file has
4506 been modified, regardless of whether the file is empty.
4507
4509 How can I use Unicode (non-ASCII) characters?
4510 You need to set locale environment variables to enable Unicode
4511 character support.
4512 If the variables have already been configured for your preference, you
4514 probably don’t have to do anything. To check the current locale
4515 configurations, you can use the locale command:
4516 $ locale
4518 LANG=
4519 LC_CTYPE="en_US.utf8"
4520 LC_NUMERIC="en_US.utf8"
4521 LC_TIME="en_US.utf8"
4522 LC_COLLATE="en_US.utf8"
4523 LC_MONETARY="en_US.utf8"
4524 LC_MESSAGES="en_US.utf8"
4525 LC_PAPER="en_US.utf8"
4526 LC_NAME="en_US.utf8"
4527 LC_ADDRESS="en_US.utf8"
4528 LC_TELEPHONE="en_US.utf8"
4529 LC_MEASUREMENT="en_US.utf8"
4530 LC_IDENTIFICATION="en_US.utf8"
4531 LC_ALL=en_US.utf8
4532 In this example, the locale command shows that all the locale setting
4534 categories are configured for the English language, the United States
4535 region, and the UTF-8 encoding.
4536 If the current configuration does not seem to match your preference,
4538 set the LC_ALL variable like this:
4539 export LC_ALL=en_US.utf8
4541 If you want to use other languages, regions, or encodings, you have to
4543 set the variable to a different value. Please consult your OS’s
4544 documentation to learn how to configure these variables in detail.
4545 If you want to apply the same configuration every time you start yash,
4547 write the command in ~/.yashrc or ~/.yash_profile.
4548 If yash still rejects Unicode characters being entered, see the section
4550 below regarding line-editing.
4551 Line-editing does not work
4553 First, type echo $TERM and see if it prints a sane value. xterm is the
4554 safest value that should work on any existing environment. Colored
4555 versions like xterm-16color and other terminal types like rxvt and
4556 vt100 may also work. All possible values can be listed by the toe
4557 command. It’s most desirable to choose a value that matches the actual
4558 terminal type you are using, but it might not work if the terminal type
4559 you chose is not supported on the system on which yash is running. If
4560 so, try changing the TERM value by export TERM=xterm, for example, to
4561 find a value that works.
4562 If line-editing works but you have trouble entering Unicode (non-ASCII)
4564 characters, try enabling the le-no-conv-meta option by set -o
4565 le-no-conv-meta.
4566
4568 This chapter defines the syntax of the shell command language.
4569 Note
4571 Some of the syntactic features described below are not supported in
4572 the POSIXly-correct mode.
4573 Tokenization
4575 The characters of the input source code are first delimited into
4576 tokens. Tokens are delimited so that the earlier token spans as long as
4577 possible. A sequence of one or more unquoted blank characters delimits
4578 a token.
4579 The following tokens are the operator tokens:
4581 & && ( ) ; ;; | || < << <& <( <<- <<< <> > >> >& >( >>| >| (newline)
4583 Note
4585 Unlike other programming languages, the newline operator is a token
4586 rather than a white space.
4587 Characters that are not blank nor part of an operator compose a word
4589 token. Words are parsed by the following parsing expression grammar:
4590 Word
4592 (WordElement / !SpecialChar .)+
4593 WordElement
4595 \ . /
4596 ' (!' .)* ' /
4598 " QuoteElement* " /
4600 Parameter /
4602 Arithmetic /
4604 CommandSubstitution
4606 QuoteElement
4608 \ ([$`"\] / <newline>) /
4609 Parameter /
4611 Arithmetic /
4613 CommandSubstitutionQuoted /
4615 ![`"\] .
4617 Parameter
4619 $ [@*#?-$! [:digit:]] /
4620 $ PortableName /
4622 $ ParameterBody
4624 PortableName
4626 ![0-9] [0-9 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_]+
4627 ParameterBody
4629 { ParameterNumber? (ParameterName / ParameterBody / $ ParameterBody
4630 / Arithmetic / CommandSubstitution) ParameterIndex?
4631 ParameterMatch? }
4632 ParameterNumber
4634 # ![}+=:/%] !([-?#] !})
4635 ParameterName
4637 [@*#?-$!] /
4638 [[:alnum:] _]+
4640 ParameterIndex
4642 [ ParameterIndexWord (, ParameterIndexWord)? ]
4643 ParameterIndexWord
4645 (WordElement / !["'],] .)+
4646 ParameterMatch
4648 :? [-+=?] ParameterMatchWord /
4649 (# / ## / % / %%) ParameterMatchWord /
4651 (:/ / / [#%/]?) ParameterMatchWordNoSlash (/ ParameterMatchWord)?
4653 ParameterMatchWord
4655 (WordElement / !["'}] .)*
4656 ParameterMatchWordNoSlash
4658 (WordElement / !["'/}] .)*
4659 Arithmetic
4661 $(( ArithmeticBody* ))
4662 ArithmeticBody
4664 \ . /
4665 Parameter /
4667 Arithmetic /
4669 CommandSubstitution /
4671 ( ArithmeticBody ) /
4673 ![`()] .
4675 CommandSubstitution
4677 $( CompleteProgram ) /
4678 ` CommandSubstitutionBody* `
4680 CommandSubstitutionQuoted
4682 $( CompleteProgram ) /
4683 ` CommandSubstitutionBodyQuoted* `
4685 CommandSubstitutionBody
4687 \ [$`\] /
4688 !` .
4690 CommandSubstitutionBodyQuoted
4692 \ [$`\`] /
4693 !` .
4695 SpecialChar
4697 [|&;<>()`\"' [:blank:]] / <newline>
4698 The set of terminals of the grammar is the set of characters that can
4700 be handled on the environment in which the shell is run (a.k.a.
4701 execution character set), with the exception that the set does not
4702 contain the null character ('\0').
4703 Strictly speaking, the definition above is not a complete parsing
4705 expression grammar because the rule for CommandSubstitution (Quoted)
4706 depends on CompleteProgram which is a non-terminal of the syntax.
4707 Token classification
4709 After a word token is delimited, the token may be further
4710 classified as an IO_NUMBER token, reserved word, name word,
4711 assignment word, or just normal word. Classification other than the
4712 normal word is applied only when applicable in the context in which
4713 the word appears. See Tokens and keywords for the list of the
4714 reserved words (keywords) and the context in which a word may be
4715 recognized as a reserved word.
4716 A token is an IO_NUMBER token iff it is composed of digit
4718 characters only and immediately followed by < or >.
4719 An assignment token is a token that starts with a name followed by
4721 =:
4722 AssignmentWord
4724 AssignmentPrefix Word
4725 AssignmentPrefix
4727 Name =
4728 Name
4730 ![[:digit:]] \[[:alnum:] _]+
4731 Comments
4733 A comment begins with # and continues up to (but not including) the
4734 next newline character. Comments are treated like a blank character
4735 and do not become part of a token. The initial # of a comment must
4736 appear as if it would otherwise be the first character of a word
4737 token; Other #s are just treated as part of a word token.
4738 Comment
4740 # (!<newline> .)*
4741 Syntax
4743 After tokens have been delimited, the sequence of the tokens is parsed
4744 according to the context-free grammar defined below, where *, +, and ?
4745 should be interpreted in the same manner as standard regular
4746 expression:
4747 CompleteProgram
4749 NL* | CompoundList
4750 CompoundList
4752 NL* AndOrList ((; | & | NL) CompleteProgram)?
4753 AndOrList
4755 Pipeline ((&& | ||) NL* Pipeline)*
4756 Pipeline
4758 !? Command (| NL* Command)*
4759 Command
4761 CompoundCommand Redirection* |
4762 FunctionDefinition |
4764 SimpleCommand
4766 CompoundCommand
4768 Subshell |
4769 Grouping |
4771 IfCommand |
4773 ForCommand |
4775 WhileCommand |
4777 CaseCommand |
4779 DoubleBracketCommand |
4781 FunctionCommand
4783 Subshell
4785 ( CompoundList )
4786 Grouping
4788 { CompoundList }
4789 IfCommand
4791 if CompoundList then CompoundList (elif CompoundList then
4792 CompoundList)* (else CompoundList)? fi
4793 ForCommand
4795 for Name ((NL* in Word*)? (; | NL) NL*)? do CompoundList done
4796 WhileCommand
4798 (while | until) CompoundList do CompoundList done
4799 CaseCommand
4801 case Word NL* in NL* CaseList? esac
4802 CaseList
4804 CaseItem (;; NL* CaseList)?
4805 CaseItem
4807 (? Word (| Word)* ) CompleteProgram
4808 DoubleBracketCommand
4810 [[ Ors ]]
4811 Ors
4813 Ands (|| Ands)*
4814 Ands
4816 Nots (&& Nots)*
4817 Nots
4819 !* Primary
4820 Primary
4822 (-b | -c | -d | -e | -f | -G | -g | -h | -k | -L | -N | -n | -O |
4823 -o | -p | -r | -S | -s | -t | -u | -w | -x | -z) Word |
4824 Word (-ef | -eq | -ge | -gt | -le | -lt | -ne | -nt | -ot | -veq |
4826 -vge | -vgt | -vle | -vlt | -vne | = | == | === | =~ | != | !== | <
4827 | >) Word |
4828 ( Ors ) |
4830 Word
4832 FunctionCommand
4834 function Word (( ))? NL* CompoundCommand Redirection*
4835 FunctionDefinition
4837 Name ( ) NL* CompoundCommand Redirection*
4838 SimpleCommand
4840 (Assignment | Redirection) SimpleCommand? |
4841 Word (Word | Redirection)*
4843 Assignment
4845 AssignmentWord |
4846 AssignmentPrefix( NL* (Word NL*)* )
4848 Redirection
4850 IO_NUMBER? RedirectionOperator Word |
4851 IO_NUMBER? <( CompleteProgram ) |
4853 IO_NUMBER? >( CompleteProgram )
4855 RedirectionOperator
4857 < | <> | > | >| | >> | >>| | <& | >& | << | <<- | <<<
4858 NL
4860 <newline>
4861 In the rule for Primary, Word tokens must not be ]]. Additionally, if a
4863 Primary starts with a Word, it must not be any of the possible unary
4864 operators allowed in the rule.
4865 In the rule for SimpleCommand, a Word token is accepted only when the
4867 token cannot be parsed as the first token of an Assignment.
4868 In the rule for Assignment, the ( token must immediately follow the
4870 AssignmentPrefix token, without any blank characters in between.
4871 Here-document contents do not appear as part of the grammar above. They
4873 are parsed just after the newline (NL) token that follows the
4874 corresponding redirection operator.
4875 Alias substitution
4877 Word tokens are subject to alias substitution.
4878 • If a word is going to be parsed as a Word of a SimpleCommand,
4880 the word is subjected to alias substitution of any kind (normal
4881 and global aliases).
4882 • If a word is the next token after the result of an alias
4884 substitution and the substitution string ends with a blank
4885 character, then the word is also subjected to alias
4886 substitution of any kind.
4887 • Other words are subjected to global alias substitution unless
4889 the shell is in the POSIXly-correct mode.
4890 Tokens that are classified as reserved words are not subject to
4892 alias substitution.
4893
4895 The alias built-in defines and/or prints aliases.
4896 Syntax
4898 • alias [-gp] [name[=value]...]
4899 Description
4901 The alias built-in defines and/or prints aliases as specified by
4902 operands. The printed aliases can be used as (part of) shell commands.
4903 The built-in prints all currently defined aliases when given no
4904 operands.
4905 Options
4907 -g, --global
4908 With this option, aliases are defined as global aliases; without
4909 this option, as normal aliases.
4910 -p, --prefix
4912 With this option, aliases are printed in a full command form like
4913 alias -g foo='bar'. Without this option, only command operands are
4914 printed like foo='bar'.
4915 Operands
4917 name
4918 The name of an alias that should be printed.
4919 name=value
4921 The name and value of an alias that is being defined.
4922 Exit status
4924 The exit status of the alias built-in is zero unless there is any
4925 error.
4926 Notes
4928 The characters that cannot be used in an alias name are the space, tab,
4929 newline, and any of =$<>\'"`;&|()#. You can use any characters in an
4930 alias value.
4931 The alias built-in is a semi-special built-in.
4933 The POSIX standard defines no options for the alias built-in, thus no
4935 options are available in the POSIXly correct mode.
4936
4938 The array built-in prints or modifies arrays.
4939 Syntax
4941 • array
4942 • array name [value...]
4944 • array -d name [index...]
4946 • array -i name index [value...]
4948 • array -s name index value
4950 Description
4952 When executed without any option or operands, the built-in prints all
4953 array definitions to the standard output in a form that can be parsed
4954 as commands.
4955 When executed with name and values (but without an option), the
4957 built-in sets the values as the values of the array named name.
4958 With the -d (--delete) option, the built-in removes the indexth values
4960 of the array named name. The number of values in the array will be
4961 decreased by the number of the indexes specified. If the indexth value
4962 does not exist, it is silently ignored.
4963 With the -i (--insert) option, the built-in inserts values into the
4965 array named name. The number of values in the array will be increased
4966 by the number of the values specified. The values are inserted between
4967 the indexth and next values. If index is zero, the values are inserted
4968 before the first value. If index is larger than the number of values in
4969 the array, the values are appended after the last element.
4970 With the -s (--set) option, the built-in sets value as the indexth
4972 value of the array named name. The array must have at least index
4973 values.
4974 Options
4976 -d, --delete
4977 Delete array values.
4978 -i, --insert
4980 Insert array values.
4981 -s, --set
4983 Set an array value.
4984 Operands
4986 name
4987 The name of an array to operate on.
4988 index
4990 The index to an array element. The first element has the index of
4991 1.
4992 value
4994 A string to which the array element is set.
4995 Exit status
4997 The exit status of the array built-in is zero unless there is any
4998 error.
4999 Notes
5001 The array built-in is not defined in the POSIX standard.
5002 The command array name value... is equivalent to the assignment
5004 name=(value...).
5005
5007 The bg built-in resumes a job in the background.
5008 Syntax
5010 • bg [job...]
5011 Description
5013 The bg built-in sends the SIGCONT signal to the specified job. As a
5014 result, the job is resumed in the background (if it has been
5015 suspended).
5016 The name of the job is printed when the job is resumed.
5018 The built-in can be used only when job control is enabled.
5020 Operands
5022 job
5023 The job ID of the job to be resumed.
5024 More than one job can be specified at a time. The current job is
5026 resumed if none is specified.
5027 The percent sign (%) at the beginning of a job ID can be omitted if
5029 the shell is not in the POSIXly-correct mode.
5030 Exit status
5032 The exit status of the bg built-in is zero unless there is any error.
5033 Notes
5035 The bg built-in is a semi-special built-in.
5036 The POSIX standard provides that the built-in shall have no effect when
5038 the job is already running. The bg built-in of yash, however, always
5039 sends the SIGCONT signal to the job.
5040
5042 The bindkey built-in prints or modifies key bindings used in
5043 line-editing.
5044 Syntax
5046 • bindkey -aev [key [command]]
5047 • bindkey -l
5049 Description
5051 When executed with the -l (--list) option, the built-in lists all
5052 available line-editing commands to the standard output.
5053 When executed with one of the other options, the built-in prints or
5055 modifies key bindings for the editing mode specified by the option:
5056 • Without key or command, all currently defined bindings are printed
5058 to the standard output in a form that can be parsed as commands
5059 that restore the current bindings when executed.
5060 • With key but without command, only the binding for the given key is
5062 printed.
5063 • With key and command, key is bound to command.
5065 Options
5067 -a, --vi-command
5068 Print or modify bindings for the vi command mode.
5069 -e, --emacs
5071 Print or modify bindings for the emacs mode.
5072 -v, --vi-insert
5074 Print or modify bindings for the vi insert mode.
5075 Operands
5077 key
5078 A character sequence of one or more keys that is bound to an
5079 editing command. The sequence may include escape sequences.
5080 command
5082 A line-editing command to which key is bound. If command is a
5083 single hyphen (-), key is unbound.
5084 Exit status
5086 The exit status of the bindkey built-in is zero unless there is any
5087 error.
5088 Notes
5090 The bindkey built-in is a semi-special built-in. In the POSIX standard,
5091 it is defined as a command with unspecified behavior.
5092
5094 The break built-in aborts a loop being executed.
5095 Syntax
5097 • break [nest]
5098 • break -i
5100 Description
5102 When executed without the -i (--iteration) option, the built-in aborts
5103 a currently executed for, while, or until loop. When executed in nested
5104 loops, it aborts the nestth innermost loop. The default nest is one. If
5105 the number of currently executed nested loops is less than nest, the
5106 built-in aborts the outermost loop.
5107 When executed with the -i (--iteration) option, the built-in aborts the
5109 currently executed (innermost) iterative execution.
5110 Options
5112 -i, --iteration
5113 Abort an iterative execution instead of a loop.
5114 Operands
5116 nest
5117 The number of loops to abort, which must be a positive integer.
5118 Exit status
5120 The exit status of the break built-in is:
5121 • zero if a loop was successfully aborted.
5123 • that of the command that was executed just before the break
5125 built-in if an iterative execution was successfully aborted.
5126 Notes
5128 The break built-in is a special built-in.
5129 The POSIX standard defines no options for the break built-in; the
5131 built-in accepts no options in the POSIXly-correct mode.
5132 Treatment of currently executed loops that are not lexically enclosing
5134 the break built-in is unspecified in POSIX. Examples of such loops
5135 include:
5136 • A loop invoking a function in which the break built-in is used.
5138 • A loop in which a trap action is executed in which the break
5140 built-in is used.
5141 Yash does not allow breaking such loops.
5143
5145 The cd built-in changes the working directory.
5146 Syntax
5148 • cd [-L|-P] [directory]
5149 Description
5151 The cd built-in changes the working directory to the directory
5152 specified by the operand.
5153 The pathname of the new working directory is assigned to the PWD
5155 variable, whose previous value is again assigned to the OLDPWD
5156 variable. The new PWD value will not contain any . or .. components
5157 except when the shell is in the POSIXly-correct mode and the new
5158 pathname begins with /...
5159 If directory is a relative path that does not start with ‘.’ or ‘..’,
5161 paths in the CDPATH variable are searched to find a new working
5162 directory. The search is done in a manner similar to the last step of
5163 command search, but a directory is sought instead of an executable
5164 regular file. If a new working directory was found from CDPATH, its
5165 pathname is printed to the standard output. If no applicable directory
5166 was found in the search, directory is simply treated as a pathname
5167 relative to the current working directory.
5168 If the working directory was successfully changed, the value of the
5170 YASH_AFTER_CD variable is executed as a command unless the shell is in
5171 the POSIXly-correct mode. If the variable is an array, its values are
5172 executed iteratively (cf. eval built-in).
5173 Options
5175 -L, --logical
5176 Symbolic links in the pathname of the new working directory are not
5177 resolved. The new value of the PWD may include pathname components
5178 that are symbolic links.
5179 -P, --physical
5181 Symbolic links in the pathname of the new working directory are
5182 resolved. The new value of the PWD variable never includes pathname
5183 components that are symbolic links.
5184 --default-directory=directory
5186 If this option is specified and the directory operand is omitted,
5187 the argument to this option is used for the directory operand. If
5188 the directory operand is specified, this option is ignored.
5189 The -L (--logical) and -P (--physical) options are mutually exclusive:
5191 only the last specified one is effective. If neither is specified, -L
5192 is assumed.
5193 Operands
5195 directory
5196 The pathname of the new working directory.
5197 If directory is a single hyphen (‘-’), the value of the OLDPWD
5199 variable is assumed for the new directory pathname, which is
5200 printed to the standard output.
5201 If directory is omitted, the working directory is changed to the
5203 directory specified by the --default-directory=... option. If that
5204 option is not specified either, the default is the home directory.
5205 Exit status
5207 The exit status of the cd built-in is zero if the working directory was
5208 successfully changed and non-zero if there was an error.
5209 Notes
5211 The cd built-in is a semi-special built-in.
5212 The POSIX standard does not define the use of the YASH_AFTER_CD
5214 variable or the --default-directory=... option. The standard does not
5215 allow using an option with a single hyphen operand.
5216 The exit status of the commands in the YASH_AFTER_CD variable does not
5218 affect that of the cd built-in.
5219
5221 The colon built-in does nothing.
5222 Syntax
5224 • : [argument...]
5225 Description
5227 The colon built-in does nothing. Any command line arguments are
5228 ignored.
5229 Exit status
5231 The exit status of the colon built-in is zero.
5232 Notes
5234 The colon built-in is a special built-in.
5235 Arguments are expanded and redirections are performed as usual. The
5237 colon and true built-ins have the same effect, but colon is a special
5238 built-in while true is a semi-special.
5239
5241 The command built-in executes or identifies a command.
5242 Syntax
5244 • command [-befp] command [argument...]
5245 • command -v|-V [-abefkp] command...
5247 Description
5249 Without the -v (--identify) or -V (--verbose-identify) option, the
5250 built-in executes command with arguments in the same manner as the last
5251 step of execution of simple commands. The command is treated as a
5252 built-in or external command or a function according to the options
5253 specified to the command built-in. The shell does not exit on argument
5254 syntax error etc. even if the command is a special built-in
5255 With the -v (--identify) option, command is identified. If the command
5257 is found in $PATH, its full pathname is printed. If it is a keyword,
5258 function, or built-in that is not found in $PATH, the command name is
5259 simply printed. If it is an alias, it is printed in the form like alias
5260 ll='ls -l'. If the command is not found, nothing is printed and the
5261 exit status is non-zero.
5262 The -V (--verbose-identify) option is similar to the -v (--identify)
5264 option, but the output format is more human-friendly.
5265 Options
5267 -a, --alias
5268 Search for the command as an alias. Must be used with the -v
5269 (--identify) or -V (--verbose-identify) option.
5270 -b, --builtin-command
5272 Search for the command as a built-in.
5273 -e, --external-command
5275 Search for the command as an external command.
5276 -f, --function
5278 Search for the command as a function.
5279 -k, --keyword
5281 Search for the command as a keyword. Must be used with the -v
5282 (--identify) or -V (--verbose-identify) option.
5283 -p, --standard-path
5285 Search the system’s default PATH instead of the current $PATH.
5286 -v, --identify
5288 Identify commands and print in the format defined in the POSIX
5289 standard.
5290 -V, --verbose-identify
5292 Identify commands and print in a human-friendly format.
5293 If none of the -a (--alias), -b (--builtin-command), -e
5295 (--external-command), -f (--function), and -k (--keyword) options is
5296 specified, the following defaults are assumed:
5297 Without the -v (--identify) or -V (--verbose-identify) option
5299 -b -e
5300 With the -v (--identify) or -V (--verbose-identify) option
5302 -a -b -e -f -k
5303 Operands
5305 command
5306 A command to be executed or identified.
5307 argument...
5309 Arguments passed to the executed command.
5310 Exit status
5312 The exit status of the command built-in is:
5313 Without the -v (--identify) or -V (--verbose-identify) option
5315 the exit status of the executed command.
5316 With the -v (--identify) or -V (--verbose-identify) option
5318 zero unless there is any error.
5319 Notes
5321 The command built-in is a semi-special built-in.
5322 In the POSIXly-correct mode, options other than -p, -v, and -V cannot
5324 be used and at most one command can be specified. The POSIX standard
5325 does not allow specifying both -v and -V together, but yash does (only
5326 the last specified one is effective).
5327
5329 The complete built-in generates completion candidates. This built-in
5330 can only be executed from completion functions during command line
5331 completion.
5332 Syntax
5334 • complete [-A pattern] [-R pattern] [-T] [-P prefix] [-S suffix]
5335 [-abcdfghjkuv] [[-O] [-D description] word...]
5336 Description
5338 The built-in generates completion candidates according to the specified
5339 arguments. No matter how candidates are generated, only candidates that
5340 match the word being completed are generated.
5341 Options
5343 -A pattern, --accept=pattern
5344 Only accept candidates that match the pattern specified by this
5345 option. When more than one of this option is specified, only
5346 candidates that match all of the patterns are generated.
5347 -D description, --description=description
5349 Give a description of the word candidates. The description is shown
5350 beside the candidates in the candidate list.
5351 -O, --option
5353 The candidates are treated as command line options. A hyphen is
5354 prepended to each candidate that is treated as an option.
5355 -P prefix, --prefix=prefix
5357 Ignore prefix of the word being completed when generating
5358 candidates. The specified prefix must be initial part of the word.
5359 If the word being completed is file:///home/user/docume for
5361 example, the command line complete -P file:// -f will generate
5362 pathname candidates that complete /home/user/docume.
5363 -R pattern, --reject=pattern
5365 Reject candidates that match the pattern specified by this option.
5366 When more than one of this option is specified, only candidates
5367 that match none of the patterns are generated.
5368 -S suffix, --suffix=suffix
5370 Append suffix to each generated candidate.
5371 -T, --no-termination
5373 Do not append a space after the word is completed. Without this
5374 option, a space is appended to the completed word so that you do
5375 not have to enter a space before the next word.
5376 Options that select candidate types
5378 -a, --alias
5379 Aliases. (same as --normal-alias --global-alias)
5380 --array-variable
5382 Arrays.
5383 --bindkey
5385 Line-editing commands the bindkey built-in accepts.
5386 -b, --builtin-command
5388 Built-in commands. (same as --special-builtin
5389 --semi-special-builtin --regular-builtin)
5390 -c, --command
5392 Commands. (same as --builtin-command --external-command
5393 --function)
5394 -d, --directory
5396 Directories.
5397 --dirstack-index
5399 Valid indices of the directory stack.
5400 --executable-file
5402 Executable regular files.
5403 --external-command
5405 External commands.
5406 -f, --file
5408 Files (including directories).
5409 --finished-job
5411 Job IDs of finished jobs.
5412 --function
5414 Functions.
5415 --global-alias
5417 Global aliases.
5418 -g, --group
5420 User groups.
5421 -h, --hostname
5423 Host names.
5424 -j, --job
5426 Job IDs.
5427 -k, --keyword
5429 Keywords.
5430 --normal-alias
5432 Normal aliases.
5433 --regular-builtin
5435 Regular built-in commands.
5436 --running-job
5438 Job IDs of jobs that are being executed.
5439 --scalar-variable
5441 Variables that are not arrays.
5442 --semi-special-builtin
5444 Semi-special built-in commands.
5445 --signal
5447 Signals.
5448 --special-builtin
5450 Special built-in commands.
5451 --stopped-job
5453 Job IDs of jobs that are suspended.
5454 -u, --username
5456 Users' log-in names.
5457 -v, --variable
5459 Variables.
5460 If the -d (--directory) option is specified without the -f (--file)
5462 option, the -S / -T options are assumed.
5463 Generated candidates for job IDs do not have leading percent signs
5465 (%). If the word being completed starts with a percent sign, the -P
5466 % option should be specified.
5467 Operands
5469 Operands are treated as completion candidates.
5470 Exit status
5472 The exit status of the built-in is zero if one or more candidates were
5473 generated, one if no candidates were generated, or larger than one if
5474 an error occurred.
5475 Notes
5477 The complete built-in is a semi-special built-in. In the POSIX
5478 standard, it is defined as a command with unspecified behavior.
5479
5481 The continue built-in skips an iteration of a loop being executed.
5482 Syntax
5484 • continue [nest]
5485 • continue -i
5487 Description
5489 When executed without the -i (--iteration) option, the built-in aborts
5490 the current iteration of for, while, or until loop and starts the next
5491 iteration of the loop. When executed in nested loops, it affects the
5492 nestth innermost loop. The default nest is one. If the number of
5493 currently executed nested loops is less than nest, the built-in affects
5494 the outermost loop.
5495 When executed with the -i (--iteration) option, the built-in aborts the
5497 current iteration of (innermost) iterative execution.
5498 Options
5500 -i, --iteration
5501 Skip an iterative execution instead of a loop.
5502 Operands
5504 nest
5505 The nestth innermost loop is affected. nest must be a positive
5506 integer.
5507 Exit status
5509 The exit status of the continue built-in is:
5510 • zero if loop iteration was successfully skipped.
5512 • that of the command that was executed just before the continue
5514 built-in if iterative execution was successfully skipped.
5515 Notes
5517 The continue built-in is a special built-in.
5518 The POSIX standard defines no options for the continue built-in; the
5520 built-in accepts no options in the POSIXly-correct mode.
5521 Treatment of currently executed loops that are not lexically enclosing
5523 the continue built-in is unspecified in POSIX. Examples of such loops
5524 include:
5525 • A loop invoking a function in which the continue built-in is used
5527 • A loop in which a trap action is executed in which the continue
5529 built-in is used
5530 Yash does not allow continuing such loops.
5532
5534 The dirs built-in prints the contents of the directory stack.
5535 Syntax
5537 • dirs [-cv] [index..]
5538 Description
5540 The directory stack is a feature that records history of working
5541 directories. You can use the pushd built-in to save a working directory
5542 in the directory stack, the popd built-in to recall the saved working
5543 directory, and the dirs built-in to see the stack contents. Those
5544 built-ins use the DIRSTACK array and the PWD variable to save the stack
5545 contents. Modifying the array means modifying the stack contents.
5546 Directory stack entries are indexed by signed integers. The entry of
5548 index +0 is the current working directory, +1 is the last saved
5549 directory, +2 is the second last, and so on. Negative indices are in
5550 the reverse order: the entry of index -0 is the first saved directory,
5551 -1 is the second, and -n is the current working directory if the stack
5552 has n entries,
5553 When executed without the -c (--clear) option, the dirs built-in prints
5555 the current contents of the directory stack to the standard output.
5556 With the -c (--clear) option, the built-in clears the directory stack.
5557 Options
5559 -c, --clear
5560 Clear the directory stack contents except for the current working
5561 directory, which has index +0.
5562 -v, --verbose
5564 Print indices when printing stack contents.
5565 Operands
5567 index
5568 The index of a stack entry to be printed.
5569 You can specify more than one index. If you do not specify any
5571 index, all the entries are printed.
5572 Exit status
5574 The exit status of the dirs built-in is zero unless there is any error.
5575 Notes
5577 The dirs built-in is a semi-special built-in. In the POSIX standard, it
5578 is defined as a command with unspecified behavior.
5579
5581 The disown built-in removes jobs.
5582 Syntax
5584 • disown [-a] [job...}
5585 Description
5587 The disown built-in removes the specified jobs from the job list. The
5588 removed jobs will no longer be job-controlled, but the job processes
5589 continue execution (unless they have been suspended).
5590 Options
5592 -a, --all
5593 Removes all jobs.
5594 Operands
5596 job
5597 The job ID of the job to be removed.
5598 You can specify more than one job ID. If you do not specify any job
5600 ID, the current job is removed. If the shell is not in the
5601 POSIXly-correct mode, the %-prefix of the job ID can be omitted.
5602 Exit status
5604 The exit status of the disown built-in is zero unless there is any
5605 error.
5606 Notes
5608 The disown built-in is a semi-special built-in. In the POSIX standard,
5609 it is defined as a command with unspecified behavior.
5610
5612 The dot built-in reads a file and executes commands in it.
5613 Syntax
5615 • . [-AL] file [argument...]
5616 Description
5618 The dot built-in reads the specified file, parses its contents as
5619 commands, and executes them in the current command execution
5620 environment.
5621 If arguments are specified, positional parameters are temporarily set
5623 to them. The positional parameters will be restored when the dot
5624 built-in finishes. If no arguments are specified, the positional
5625 parameters are not changed.
5626 If file does not contain any slashes, the shell searches $PATH for a
5628 readable (but not necessarily executable) shell script file whose name
5629 is file in the same manner as command search. If no such file was
5630 found, the shell searches the current working directory for a file
5631 unless in the POSIXly-correct mode. To ensure that the file in the
5632 current working directory is used, start file with ‘./’.
5633 Options
5635 -A, --no-alias
5636 Disable alias substitution while parsing.
5637 -L, --autoload
5639 Search $YASH_LOADPATH instead of $PATH, regardless of whether file
5640 contains slashes. The file value is not considered relative to the
5641 current working directory.
5642 The dot built-in treats as operands any command line arguments after
5644 the first operand.
5645 Operands
5647 file
5648 The pathname of a file to be read.
5649 arguments...
5651 Strings to which positional parameters are set while execution.
5652 Exit status
5654 The exit status of the dot built-in is that of the last command
5655 executed. The exit status is zero if the file contains no commands to
5656 execute and non-zero if a file was not found or could not be opened.
5657 Notes
5659 The dot built-in is a special built-in.
5660 A non-interactive shell immediately exits with a non-zero exit status
5662 if the dot built-in fails to find or open a file to execute.
5663 The POSIX standard defines no options for the dot built-in; the
5665 built-in accepts no options in the POSIXly-correct mode.
5666 The POSIX standard does not define the arguments... operands. It is an
5668 error to specify the arguments... operands in the POSIXly-correct mode.
5669
5671 The echo built-in prints its arguments.
5672 Syntax
5674 • echo [string...]
5675 The built-in treats all command line arguments as operands except for
5677 the options described below. Any word that cannot be parsed as an
5678 acceptable option is treated as an operand. Options must precede all
5679 operands. Syntax errors never happen in the echo built-in.
5680 Description
5682 The echo built-in prints the operand strings followed by a newline to
5683 the standard output. The strings are each separated by a space.
5684 Escape sequences
5686 The ECHO_STYLE variable and the -e option enable escape sequences
5687 that are replaced with corresponding characters:
5688 \a
5690 Bell character (ASCII code: 7)
5691 \b
5693 Backspace (ASCII code: 8)
5694 \c
5696 Nothing. After this escape sequence, no characters are printed
5697 at all.
5698 \e
5700 Escape character (ASCII code: 27)
5701 \f
5703 Form feed character (ASCII code: 12)
5704 \n
5706 Newline character (ASCII code: 10)
5707 \r
5709 Carriage return character (ASCII code: 13)
5710 \t
5712 Horizontal tab character (ASCII code: 9)
5713 \v
5715 Vertical tab character (ASCII code: 11)
5716 \\
5718 Backslash
5719 \0xxx
5721 Character whose code is xxx, where xxx is an octal number of at
5722 most three digits.
5723 When escape sequences are not enabled, they are just printed
5725 intact.
5726 ECHO_STYLE variable
5728 The ECHO_STYLE variable defines which options are accepted and
5729 whether escape sequences are enabled by default. The variable value
5730 should be set to one of the following:
5731 SYSV, XSI
5733 No options are accepted. Escape sequences are always enabled.
5734 BSD
5736 The -n option is accepted. Escape sequences are never enabled.
5737 GNU
5739 The -n, -e, and -E options are accepted. Escape sequences are
5740 not enabled by default, but can be enabled by the -e option.
5741 ZSH
5743 The -n, -e, and -E options are accepted. Escape sequences are
5744 enabled by default, but can be disabled by the -E option.
5745 DASH
5747 The -n option is accepted. Escape sequences are always enabled.
5748 RAW
5750 No options are accepted. Escape sequences are never enabled.
5751 When the ECHO_STYLE variable is not set, it defaults to SYSV.
5753 Options
5755 -n
5756 Do not print a newline at the end.
5757 -e
5759 Enable escape sequences.
5760 -E
5762 Disable escape sequences.
5763 Exit status
5765 The exit status of the echo built-in is zero unless there is any error.
5766 Notes
5768 The POSIX standard does not define the ECHO_STYLE variable nor any
5769 options for the built-in. According to POSIX, the behavior of the
5770 built-in is implementation-defined when the first argument is -n or
5771 when any argument contains a backslash. For maximum portability, the
5772 printf built-in should be preferred over the echo built-in.
5773 Although many values for the ECHO_STYLE variable are defined on the
5775 basis of other existing implementations, yash is not intended to
5776 exactly imitate those originals. Zsh’s echo built-in interprets a
5777 single hyphen argument as a separator between options and operands.
5778 Yash does not support such use of hyphen.
5779
5781 The eval built-in evaluates operands as commands.
5782 Syntax
5784 • eval [-i] [command...]
5785 The eval built-in requires that all options precede operands. Any
5787 command line arguments after the first operand are all treated as
5788 operands.
5789 Description
5791 The eval parses operands as commands and executes them in the current
5792 command execution environment.
5793 When executed without the -i (--iteration) option, all the operands are
5795 concatenated into one string (with a space inserted between each
5796 operand) and parsed/executed at once.
5797 With the -i (--iteration) option, the built-in performs iterative
5799 execution: operands are parsed/executed one by one. If the continue
5800 built-in is executed with the -i (--iteration) option during the
5801 iterative execution, the execution of the current operand is aborted
5802 and the next operand is parsed/executed immediately. The break built-in
5803 with the -i (--iteration) option is similar but the remaining operands
5804 are not parsed/executed. The value of the ? special parameter is saved
5805 before the iterative execution is started. The parameter value is
5806 restored to the saved one after each iteration.
5807 Options
5809 -i, --iteration
5810 Perform iterative execution.
5811 Operands
5813 command
5814 A string that is parsed and executed as commands.
5815 Exit status
5817 The exit status is zero if no command was specified or command
5818 contained no actual command that can be executed. Otherwise, that is,
5819 if the eval built-in executed one or more commands, the exit status of
5820 the eval built-in is that of the last executed command.
5821 Notes
5823 The eval built-in is a special built-in.
5824 The POSIX standard defines no options for the eval built-in; the
5826 built-in accepts no options in the POSIXly-correct mode.
5827
5829 The exec built-in replaces the shell process with another external
5830 command.
5831 Syntax
5833 • exec [-cf] [-a name] [command [argument...]]
5834 The exec built-in requires that all options precede operands. It is
5836 important so that options to the exec built-in are not confused with
5837 options to command. Any command line arguments after command are
5838 treated as arguments.
5839 Description
5841 When the exec built-in is executed with command, the shell executes
5842 command with arguments in a manner similar to the last step of
5843 execution of a simple command. The differences are that command is
5844 always treated as an external command ignoring any existing functions
5845 and built-ins and that the exec system call that starts the external
5846 command is called in the current command execution environment instead
5847 of a subshell, replacing the shell process with the new command
5848 process.
5849 If the shell is in the POSIXly-correct mode or not interactive, failure
5851 in execution of command causes the shell to exit immediately.
5852 If an interactive shell that is not in the POSIXly-correct mode has a
5854 stopped job, the shell prints a warning message and refuses to execute
5855 command. Once the shell process is replaced with an external command,
5856 information about the shell’s jobs is lost, so you will have to resume
5857 or kill the stopped jobs by sending signals by hand. To force the shell
5858 to execute command regardless, specify the -f (--force) option.
5859 When executed without command, the built-in does nothing. As a side
5861 effect, however, redirection applied to the built-in remains in the
5862 current command execution environment even after the built-in finished.
5863 Options
5865 -a name, --as=name
5866 Pass name, instead of command, to the external command as its name.
5867 -c, --clear
5869 Pass to the external command only variables that are assigned in
5870 the simple command in which the built-in is being executed. Other
5871 environment variables are not passed to the command.
5872 -f, --force
5874 Suppress warnings that would prevent command execution.
5875 Operands
5877 command
5878 An external command to be executed.
5879 argument...
5881 Arguments to be passed to the command.
5882 Exit status
5884 If the shell process was successfully replaced with the external
5885 command, there is no exit status since the shell process no longer
5886 exists.
5887 The exit status is:
5889 • 127 if the command was not found,
5891 • 126 if the command was found but could not be executed, and
5893 • zero if no command was specified.
5895 Notes
5897 The exec built-in is a special built-in.
5898 The POSIX standard defines no options for the exec built-in; the
5900 built-in accepts no options in the POSIXly-correct mode.
5901
5903 The exit built-in causes the shell process to exit.
5904 Syntax
5906 • exit [-f] [exit_status]
5907 Description
5909 The exit built-in causes the current shell (or subshell) process to
5910 exit.
5911 If an interactive shell has a stopped job, the shell prints a warning
5913 message and refuses to exit. To force the shell to exit regardless,
5914 specify the -f (--force) option or execute the built-in twice in a row.
5915 If an EXIT trap has been set, the shell executes the trap before
5917 exiting.
5918 Options
5920 -f, --force
5921 Suppress warnings that would prevent the shell from exiting.
5922 Operands
5924 exit_status
5925 A non-negative integer that will be the exit status of the exiting
5926 shell.
5927 If this operand is omitted, the exit status of the shell will be
5929 that of the last command executed before the exit built-in (but, if
5930 the built-in is executed during a trap, the exit status will be
5931 that of the last command before the trap is entered).
5932 If exit_status is 256 or larger, the actual exit status will be the
5934 remainder of exit_status divided by 256.
5935 Exit status
5937 Because the built-in causes the shell to exit, there is no exit status
5938 of the built-in.
5939 As an exception, if the shell refused to exit, the exit status of the
5941 built-in is non-zero.
5942 Notes
5944 The exit built-in is a special built-in.
5945 The POSIX standard defines no options for the exit built-in; the
5947 built-in accepts no options in the POSIXly-correct mode.
5948 The POSIX standard provides that the exit_status operand should be
5950 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
5951 an extension.
5952 If the built-in is executed during an EXIT trap, the shell just exits
5954 without executing the trap again. If exit_status was not specified, the
5955 exit status of the shell is what the exit status would be if the trap
5956 had not been set. See also Termination of the shell.
5957
5959 The export built-in marks variables for export to child processes.
5960 Syntax
5962 • export [-prX] [name[=value]...]
5963 Description
5965 The export built-in is equivalent to the typeset built-in with the -gx
5966 option.
5967 Notes
5969 The export built-in is a special built-in.
5970 The POSIX standard defines the -p option only; other options cannot be
5972 used in the POSIXly-correct mode. The POSIX does not allow using the
5973 option together with operands.
5974
5976 The false built-in does nothing unsuccessfully.
5977 Syntax
5979 • false
5980 Description
5982 The false built-in does nothing. Any command line arguments are
5983 ignored.
5984 Exit status
5986 The exit status of the false built-in is non-zero.
5987 Notes
5989 The false built-in is a semi-special built-in.
5990
5992 The fc built-in re-executes or prints commands from command history.
5993 Syntax
5995 • fc [-qr] [-e editor] [start [end]]
5996 • fc -s[q] [old=new] [start]
5998 • fc -l[nrv] [start [end]]
6000 Description
6002 When executed without the -l (--list) option, the built-in executes the
6003 commands in the command history range specified by the operands. If the
6004 -s (--silent) option is not specified, the shell invokes an editor
6005 which allows you to edit the commands before they are executed. The
6006 commands are executed when you quit the editor. If the -s (--silent)
6007 option is specified, the commands are immediately executed. In either
6008 case, the executed commands are printed to the standard output and
6009 added to the history.
6010 When executed with the -l (--list) option, the built-in prints the
6012 commands in the command history range specified by the operands. By
6013 default, commands are printed with their history entry numbers, but
6014 output format can be changed using the -n (--no-numbers)) and -v
6015 (--verbose) options.
6016 Options
6018 -e editor, --editor=editor
6019 Specify an editor that is used to edit commands.
6020 If this option is not specified, the value of the FCEDIT variable
6022 is used. If the variable is not set either, ed is used.
6023 -l, --list
6025 Print command history entries.
6026 -n, --no-numbers
6028 Don’t print entry numbers when printing history entries.
6029 -q, --quiet
6031 Don’t print commands before executing.
6032 -r, --reverse
6034 Reverse the order of command entries in the range.
6035 -s, --silent
6037 Execute commands without editing them.
6038 -v, --verbose
6040 Print execution time before each history entry when printing.
6041 Operands
6043 start and end
6044 The start and end operands specify a range of command history
6045 entries that are executed or printed. If one of the operands is an
6046 integer, it is treated as a history entry number. A negative
6047 integer means the nth most recent entry where n is the absolute
6048 value of the integer. If one of the operands is not an integer, it
6049 is treated as part of a command string: the most recent entry that
6050 starts with the string is selected as the start or end of the
6051 range.
6052 If the first entry of the range that is specified by start is newer
6054 than the last entry of the range that is specified by end, the
6055 range is reversed as if the -r (--reverse) option was specified.
6056 (If the option is already specified, it is cancelled.)
6057 The default values for start and end are:
6059 ┌──────┬─────────┬───────────────┐
6061 │ │ with -l │ without -l │
6062 ├──────┼─────────┼───────────────┤
6063 │start │ -16 │ -1 │
6064 ├──────┼─────────┼───────────────┤
6065 │end │ -16 │ same as start │
6066 └──────┴─────────┴───────────────┘
6067 old=new
6069 An operand of this format replaces part of the command string. If
6070 the command string contains old, it is replaced with new and the
6071 new string is executed. Only the first occurrence of old is
6072 replaced.
6073 Exit status
6075 If commands was executed, the exit status of the fc built-in is that of
6076 the last executed command. Otherwise, the exit status is zero unless
6077 there is any error.
6078 Notes
6080 The fc built-in is a semi-special built-in.
6081 The POSIX standard does not define the -q (--quiet) or -v (--verbose)
6083 options, so they cannot be used in the POSIXly-correct mode.
6084 Command history cannot be modified during line-editing.
6086
6088 The fg built-in resumes a job in the foreground.
6089 Syntax
6091 • fg [job...]
6092 Description
6094 The fg built-in brings the specified job to the foreground and sends
6095 the SIGCONT signal to the job. As a result, the job is resumed in the
6096 foreground (if it has been suspended). The built-in then waits for the
6097 job to finish and returns the exit status of it.
6098 The name of the job is printed when the job is resumed. When not in the
6100 POSIXly-correct mode, the job number is also printed.
6101 The built-in can be used only when job control is enabled.
6103 Operands
6105 job
6106 The job ID of the job to be resumed.
6107 If more than one job is specified, they are resumed in order, one
6109 at a time. The current job is resumed if none is specified.
6110 The percent sign (%) at the beginning of a job ID can be omitted if
6112 the shell is not in the POSIXly-correct mode.
6113 Exit status
6115 The exit status of the fg built-in is that of the (last) job resumed.
6116 The exit status is non-zero when there was some error.
6117 Notes
6119 The fg built-in is a semi-special built-in.
6120 You cannot specify more than one job in the POSIXly-correct mode.
6122
6124 The getopts built-in parses command options.
6125 Syntax
6127 • getopts optionlist variable [argument...]
6128 Description
6130 The getopts built-in parses single-character options that appear in
6131 arguments. Each time the built-in is invoked, it parses one option and
6132 assigns the option character to variable.
6133 The optionlist operand is a list of option characters that should be
6135 accepted by the parser. In optionlist, an option that takes an argument
6136 should be specified as the option character followed by a colon. For
6137 example, if you want the -a, -b and -c options to be parsed and the -b
6138 option to take an argument, then optionlist should be ab:c.
6139 When an option that takes an argument is parsed, the argument is
6141 assigned to the OPTARG variable.
6142 When an option that is not specified in optionlist is found or when an
6144 option argument is missing, the result depends on the first character
6145 of optionlist:
6146 • If optionlist starts with a colon, the option character is assigned
6148 to the OPTARG variable and variable is set to either ? (when the
6149 option is not in optionlist) or : (when the option argument is
6150 missing).
6151 • Otherwise, variable is set to ?, the OPTARG variable is unset, and
6153 an error message is printed.
6154 The built-in parses one option for each execution. For all options in a
6156 set of command line arguments to be parsed, the built-in has to be
6157 executed repeatedly with the same arguments. The built-in uses the
6158 OPTIND variable to remember which argument should be parsed next. When
6159 the built-in is invoked for the first time, the variable value must be
6160 1, which is the default value. You must not modify the variable until
6161 all the options have been parsed, when the built-in sets the variable
6162 to the index of the first operand in arguments. (If there are no
6163 operands, it will be set to the number of arguments plus one.)
6164 When you want to start parsing a new set of arguments, you have to
6166 reset the OPTIND variable to 1 beforehand.
6167 Operands
6169 optionlist
6170 A list of options that should be accepted as valid options in
6171 parsing.
6172 variable
6174 The name of a variable the result is to be assigned to.
6175 arguments
6177 Command line arguments that are to be parsed.
6178 When no arguments are given, the positional parameters are parsed.
6180 Exit status
6182 If an option is found, whether or not it is specified in optionlist,
6183 the exit status is zero. If there is no more option to be parsed, the
6184 exit status is non-zero.
6185 Example
6187 aopt=false bopt= copt=false
6188 while getopts ab:c opt
6189 do
6190 case $opt in
6191 a) aopt=true ;;
6192 b) bopt=$OPTARG ;;
6193 c) copt=true ;;
6194 \?) return 2 ;;
6195 esac
6196 done
6197 if $aopt; then echo Option -a specified; fi
6198 if [ -n "$bopt" ]; then echo Option -b $bopt specified; fi
6199 if $copt; then echo Option -c specified; fi
6200 shift $((OPTIND - 1))
6201 echo Operands are: $*
6202 Notes
6204 In arguments that are parsed, options must precede operands. The
6205 built-in ends parsing when it encounters the first operand.
6206 The getopts built-in is a semi-special built-in.
6208 The POSIX standard does not specify what will happen when the OPTIND
6210 variable is assigned a value other than 1.
6211 In the POSIXly-correct mode, option characters in optionlist must be
6213 alphanumeric.
6214
6216 The hash built-in remembers, forgets, or reports command locations.
6217 Syntax
6219 • hash command...
6220 • hash -r [command...]
6222 • hash [-a]
6224 • hash -d user...
6226 • hash -dr [user...]
6228 • hash -d
6230 Description
6232 When executed with commands but without options, the built-in
6233 immediately performs command path search and caches commands' full
6234 paths.
6235 When executed with the -r (--remove) option, it removes the paths of
6237 commands (or all cached paths if none specified) from the cache.
6238 When executed without options or commands, it prints the currently
6240 cached paths to the standard output.
6241 With the -d (--directory) option, the built-in does the same things to
6243 the home directory cache, rather than the command path cache. Cached
6244 home directory paths are used in tilde expansion.
6245 Options
6247 -a, --all
6248 Print all cached paths.
6249 Without this option, paths for built-ins are not printed.
6251 -d, --directory
6253 Affect the home directory cache instead of the command path cache.
6254 -r, --remove
6256 Remove cached paths.
6257 Operands
6259 command
6260 The name of an external command (that does not contain any slash).
6261 user
6263 A user name.
6264 Exit status
6266 The exit status of the hash built-in is zero unless there is any error.
6267 Notes
6269 The shell automatically caches command and directory paths when
6270 executing a command or performing tilde expansion, so normally there is
6271 no need to use this built-in explicitly to cache paths.
6272 Assigning a value to the PATH variable removes all command paths from
6274 the cache as if hash -r was executed.
6275 The POSIX standard defines the -r option only: other options cannot be
6277 used in the POSIXly-correct mode.
6278 The hash built-in is a semi-special built-in.
6280
6282 The help built-in prints usage of built-ins.
6283 Syntax
6285 • help [built-in...]
6286 Description
6288 The help built-in prints a description of built-ins.
6289 Operands
6291 built-ins
6292 Names of built-ins.
6293 Exit status
6295 The exit status of the help built-in is zero unless there is any error.
6296 Notes
6298 The help built-in is a semi-special built-in. In the POSIX standard, it
6299 is defined as a command with unspecified behavior.
6300 Many built-ins of yash accept the --help option that prints the same
6302 description.
6303
6305 The history built-in prints or edits command history.
6306 Syntax
6308 • history [-cF] [-d entry] [-s command] [-r file] [-w file] [count]
6309 Description
6311 The history built-in prints or edits command history.
6312 When executed with an option, the built-in edits history according to
6314 the option. If more than one option is specified, each option is
6315 processed in order.
6316 When executed with the count operand, the built-in prints the most
6318 recent count history entries to the standard output in the same manner
6319 as the fc built-in.
6320 When executed with neither options nor operands, the built-in prints
6322 the whole history.
6323 Options
6325 -c, --clear
6326 Clear all history entries completely.
6327 -d entry, --delete=entry
6329 Delete the specified entry. The entry should be specified in the
6330 same manner as the start and end operands of the fc built-in.
6331 -F, --flush-file
6333 Rebuild the history file. This operation removes unused old data
6334 from the file.
6335 -r file, --read=file
6337 Read command lines from file and add them to the history. The file
6338 contents are treated as lines of simple text.
6339 -s command, --set=command
6341 Add command as a new history entry after removing the most recent
6342 entry.
6343 -w file, --write=file
6345 Write the whole history to file. Any existing data in the file will
6346 be lost. The output format is lines of simple text, each of which
6347 is a command string.
6348 Operands
6350 count
6351 The number of entries to be printed.
6352 Exit status
6354 The exit status of the history built-in is zero unless there is any
6355 error.
6356 Notes
6358 The history built-in is a semi-special built-in. In the POSIX standard,
6359 it is defined as a command with unspecified behavior.
6360 Command history cannot be modified during line-editing.
6362
6364 The jobs built-in reports job status.
6365 Syntax
6367 • jobs [-lnprs] [job...]
6368 Description
6370 The jobs built-in prints information of jobs the shell is currently
6371 controlling.
6372 By default, the following information is printed for each job, line by
6374 line:
6375 • the job number,
6377 • the + or - symbol if the job is the current or previous job,
6379 respectively,
6380 • the status, and
6382 • the command string.
6384 Options
6386 -l, --verbose
6387 Print the process ID, status, and command string for each process
6388 in the jobs.
6389 -n, --new
6391 Print new jobs only: jobs whose status has never been reported
6392 since the status changed.
6393 -p, --pgid-only
6395 Print process group IDs of jobs only.
6396 -r, --running-only
6398 Print running jobs only.
6399 -s, --stopped-only
6401 Print stopped jobs only.
6402 Operands
6404 jobs
6405 The job IDs of jobs to be reported. When no job is specified, all
6406 jobs under the shell’s control are reported.
6407 The percent sign (%) at the beginning of a job ID can be omitted if
6409 the shell is not in the POSIXly-correct mode.
6410 Exit status
6412 The exit status of the jobs built-in is zero unless there is any error.
6413 Notes
6415 The jobs built-in is a semi-special built-in.
6416 The POSIX standard defines the -l and -p options only: other options
6418 cannot be used in the POSIXly-correct mode. In the POSIXly-correct
6419 mode, the effect of the -l option is different in that status is
6420 reported for each job rather than for each process.
6421 The process group ID of a job executed by yash is equal to the process
6423 ID of the first command of the pipeline that forms the job.
6424
6426 The kill built-in sends a signal to processes.
6427 Syntax
6429 • kill [-signal|-s signal|-n signal] process...
6430 • kill -l [-v] [signal...]
6432 The kill built-in requires that all options precede operands. Any
6434 command line arguments after the first operand are all treated as
6435 operands.
6436 Description
6438 When executed without the -l option, the built-in sends a signal to
6439 processes. The signal sent can be specified by option. The SIGTERM
6440 signal is sent if no signal is specified.
6441 When executed with the -l option, the built-in prints information of
6443 signals to the standard output. If no signal is specified, information
6444 of all signals is printed.
6445 Options
6447 Signal-specifying options
6448 -signal, -s signal, -n signal
6449 A signal-specifying option specifies a signal to be sent to
6450 processes. signal can be specified by name or number. If
6451 number 0 is specified, the built-in checks if a signal could be
6452 sent to the processes but no signal is actually sent. Signal
6453 names are case-insensitive.
6454 You can specify at most one signal-specifying option at a time.
6456 Other options
6458 -l
6459 Print signal information instead of sending a signal.
6460 -v
6462 Print more signal information.
6463 Without this option, the built-in prints the signal name only.
6465 This option adds the signal number and a short description.
6466 When the -v option is specified, the -l option can be omitted.
6468 Operands
6470 processes
6471 Specify processes to which a signal is sent.
6472 Processes can be specified by the process ID, the process group ID,
6474 or the job ID. The process group ID must be prefixed with a hyphen
6475 (-) so that it is not treated as a process ID.
6476 When 0 is specified as process, the signal is sent to the process
6478 group to which the shell process belongs. When -1 is specified, the
6479 signal is sent to all processes on the system.
6480 signal
6482 Specify a signal of which information is printed.
6483 The signal can be specified by the name, the number, or the exit
6485 status of a command that was killed by the signal.
6486 Exit status
6488 The exit status of the kill built-in is zero unless there is any error.
6489 If the signal was sent to at least one process, the exit status is zero
6490 even if the signal was not sent to all of the specified processes.
6491 Notes
6493 The kill built-in is a semi-special built-in.
6494 Command arguments that start with a hyphen should be used with care.
6496 The command kill -1 -2, for example, sends signal 1 to process group 2
6497 since -1 is treated as a signal-specifying option and -2 as an operand
6498 that specifies a process group. The commands kill -- -1 -2 and kill
6499 -TERM -1 -2, on the other hand, treats both -1 and -2 as operands.
6500 The POSIX standard does not define the -n or -v options, so they cannot
6502 be used in the POSIXly-correct mode. The standard does not allow
6503 specifying a signal number as the argument of the -s option or a signal
6504 name as the signal operand.
6505 The standard requires signal names to be specified without the SIG
6507 prefix, like INT and QUIT. If the shell is not in the POSIXly-correct
6508 mode, the built-in accepts SIG-prefixed signal names as well.
6509
6511 The local built-in prints or sets local variables.
6512 Syntax
6514 • local [-rxX] [name[=value]...]
6515 Description
6517 The local built-in is equivalent to the typeset built-in except that
6518 the -f (--functions) and -g (--global) options cannot be used.
6519 Notes
6521 The local built-in is a semi-special built-in. In the POSIX standard,
6522 it is defined as a command with unspecified behavior.
6523
6525 The popd built-in pops a directory from the directory stack.
6526 Syntax
6528 • popd [index]
6529 Description
6531 The popd built-in removes the last entry from the directory stack,
6532 returning to the previous working directory. If index is given, the
6533 entry specified by index is removed instead of the last one.
6534 Operands
6536 index
6537 The index of a directory stack entry you want to remove.
6538 If omitted, +0 (the last entry) is assumed.
6540 Exit status
6542 The exit status of the popd built-in is zero unless there is any error.
6543 Notes
6545 It is an error to use this built-in when there is only one directory
6546 stack entry.
6547 The popd built-in is a semi-special built-in. In the POSIX standard, it
6549 is defined as a command with unspecified behavior.
6550
6552 The printf built-in prints formatted values.
6553 Syntax
6555 • printf format [value...]
6556 Description
6558 The printf built-in formats values according to format and prints them
6559 to the standard output. Unlike the echo built-in, the printf built-in
6560 does not print a newline automatically.
6561 The formatting process is very similar to that of the printf function
6563 in the C programming language. You can use conversion specifications
6564 (which start with %) and escape sequences (which start with \) in
6565 format. Any other characters that are not part of a conversion
6566 specification or escape sequence are printed literally.
6567 Conversion specifications
6569 A conversion specification starts with a percent sign (%).
6570 A conversion specification except %% consumes a value, which is
6572 formatted according to the specification and printed. Each
6573 conversion specification consumes one value in the order of
6574 appearance. If there are more values than conversion
6575 specifications, the entire format is re-processed until all the
6576 values are consumed. If a value to be consumed is missing, it is
6577 assumed to be an empty string (if the specification requires a
6578 string) or zero (if a number). If no values are given, format is
6579 processed just once.
6580 Available conversion specifications are:
6582 %d, %i
6584 prints a signed integer in decimal
6585 %u
6587 prints an unsigned integer in decimal
6588 %o
6590 prints an unsigned integer in octal
6591 %x
6593 prints an unsigned integer in lowercase hexadecimal
6594 %X
6596 prints an unsigned integer in uppercase hexadecimal
6597 %f
6599 prints a floating-point number in lowercase
6600 %F
6602 prints a floating-point number in uppercase
6603 %e
6605 prints a floating-point number with exponent in lowercase
6606 %E
6608 prints a floating-point number with exponent in uppercase
6609 %g
6611 the same as %f or %e, automatically selected
6612 %G
6614 the same as %F or %E, automatically selected
6615 %c
6617 prints the first character of string
6618 %s
6620 prints a string
6621 %b
6623 prints a string (recognizing escape sequences like the echo
6624 built-in)
6625 %%
6627 prints a percent sign (%)
6628 For %g and %G, the specification that is actually used is %f or %F
6630 if the exponent part is between -5 and the precision (exclusive);
6631 %e or %E otherwise.
6632 In a conversion specification except %%, the leading percent sign
6634 may be followed by flags, field width, and/or precision in this
6635 order.
6636 The flags are a sequence of any number of the following characters:
6638 Minus sign (-)
6640 With this flag, spaces are appended to the formatted value to
6641 fill up to the field width. Otherwise, spaces are prepended.
6642 Plus sign (+)
6644 A plus or minus sign is always prepended to a number.
6645 Space ( )
6647 A space is prepended to a formatted number if it has no plus or
6648 minus sign.
6649 Hash sign (#)
6651 The value is formatted in an alternative form: For %o, the
6652 printed octal integer has at least one leading zero. For %x and
6653 %X, a non-zero integer is formatted with 0x and 0X prefixes,
6654 respectively. For %e, %E, %f, %F, %g, and %G, a decimal mark
6655 (a.k.a. radix character) is always printed even if the value is
6656 an exact integer. For %g and %G, the printed number has at
6657 least one digit in the fractional part.
6658 Zero (0)
6660 Zeros are prepended to a formatted number to fill up to the
6661 field width. This flag is ignored if the minus flag is
6662 specified or if the conversion specification is %d, %i, %u, %o,
6663 %x, or %X with a precision.
6664 A field width is specified as a decimal integer that has no leading
6666 zeros.
6667 A field width defines a minimum byte count of a formatted value. If
6669 the formatted value does not reach the minimum byte count, so many
6670 spaces are prepended that the printed value has the specified byte
6671 count.
6672 A precision is specified as a period (.) followed by a decimal
6674 integer. If the integer is omitted after the period, the precision
6675 is assumed to be zero.
6676 For conversion specifications %d, %i, %u, %o, %x, and %X, a
6678 precision defines a minimum digit count. If the formatted integer
6679 does not reach the minimum digit count, so many zeros are prepended
6680 that the printed integer has the specified number of digits. The
6681 default precision is one for these conversion specifications.
6682 For conversion specifications %e, %E, %f, and %F, a precision
6684 defines the number of digits after the decimal mark. The default
6685 precision is six for these conversion specifications.
6686 For conversion specifications %g, and %G, a precision defines a
6688 maximum number of significant digits in the printed value. The
6689 default precision is six for these conversion specifications.
6690 For conversion specifications %s, and %b, a precision defines a
6692 maximum byte count of the printed string. The default precision is
6693 infinity for these conversion specifications.
6694 In the conversion specification %08.3f, the zero flag is specified,
6696 the field width is 8, and the precision is 3. If this specification
6697 is applied to value 12.34, the output will be 0012.340.
6698 Escape sequences
6700 The following escape sequences are recognized in format:
6701 \a
6703 Bell character (ASCII code: 7)
6704 \b
6706 Backspace (ASCII code: 8)
6707 \f
6709 Form feed character (ASCII code: 12)
6710 \n
6712 Newline character (ASCII code: 10)
6713 \r
6715 Carriage return character (ASCII code: 13)
6716 \t
6718 Horizontal tab character (ASCII code: 9)
6719 \v
6721 Vertical tab character (ASCII code: 11)
6722 \\
6724 Backslash
6725 \"
6727 Double quotation
6728 \'
6730 Single quotation (apostrophe)
6731 \xxx
6733 Character whose code is xxx, where xxx is an octal number of at
6734 most three digits.
6735 Operands
6737 format
6738 A string that defines how values should be formatted.
6739 values
6741 Values that are formatted according to format.
6742 A value is either a number or a string.
6744 When a numeric value is required, value can be a single or double
6746 quotation followed by a character, instead of a normal number. For
6747 example, the command printf '%d' '"3' will print 51 on a typical
6748 environment where character 3 has character code 51.
6749 Exit status
6751 The exit status of the printf built-in is zero unless there is any
6752 error.
6753 Notes
6755 The POSIX standard does not precisely define how multibyte characters
6756 should be handled by the built-in. When you use the %s conversion
6757 specification with precision or the %c conversion specification, you
6758 may obtain unexpected results if the formatted value contains a
6759 character that is represented by more than one byte. Yash never prints
6760 only part of the bytes that represent a single multibyte character
6761 because all multibyte characters are converted to wide characters when
6762 processed in the shell.
6763 If the shell is not in the POSIXly-correct mode and the “long double”
6765 floating-point arithmetic is supported on the running system, then
6766 “long double” is used for floating-point conversion specifications.
6767 Otherwise, “double” is used.
6768
6770 The pushd built-in pushes a directory into the directory stack.
6771 Syntax
6773 • pushd [-L|-P] [directory]
6774 Description
6776 The pushd built-in changes the working directory to directory in the
6777 same manner as the cd built-in and adds it to the directory stack. If
6778 the working directory could not be changed successfully, the stack is
6779 not modified.
6780 Options
6782 The pushd built-in accepts the following option as well as the options
6783 that can be used for the cd built-in:
6784 --remove-duplicates
6786 If the new working directory has already been in the directory
6787 stack, the existing entry is removed from the stack before the new
6788 directory is pushed into the stack.
6789 Operands
6791 directory
6792 The pathname of the new working directory.
6793 If directory is a single hyphen (‘-’), the value of the OLDPWD
6795 variable is assumed for the new directory pathname, which is
6796 printed to the standard output.
6797 If directory is an integer with a plus or minus sign, it is
6799 considered as an entry index of the directory stack. The entry is
6800 removed from the stack and then pushed to the stack again.
6801 If directory is omitted, the working directory is changed to the
6803 directory specified by the --default-directory=... option. If that
6804 option is not specified either, the default is index +1.
6805 Exit status
6807 The exit status of the pushd built-in is zero unless there is any
6808 error.
6809 Notes
6811 The pushd built-in is a semi-special built-in. In the POSIX standard,
6812 it is defined as a command with unspecified behavior.
6813
6815 The pwd built-in prints the current working directory.
6816 Syntax
6818 • pwd [-L|-P]
6819 Description
6821 The pwd built-in prints an absolute path to the shell’s current working
6822 directory to the standard output.
6823 Options
6825 -L, --logical
6826 If the value of the PWD variable is an absolute path to the shell’s
6827 working directory and the path does not contain any . or ..
6828 components, then the path is printed. Otherwise, the printed path
6829 is the same as when the -P option is specified.
6830 -P, --physical
6832 The printed path does not contain any . or .. components,
6833 symbolic link components, or redundant slashes.
6834 The -L (--logical) and -P (--physical) options are mutually exclusive:
6836 only the last specified one is effective. If neither is specified, -L
6837 is assumed.
6838 Exit status
6840 The exit status of the pwd built-in is zero unless there is any error.
6841 Notes
6843 The pwd built-in is a semi-special built-in.
6844
6846 The read built-in reads a line from the standard input.
6847 Syntax
6849 • read [-Aer] [-P|-p] variable...
6850 Description
6852 The read built-in reads a line of string from the standard input and
6853 assigns it to the specified variables.
6854 If the -r (--raw-mode) option is specified, all characters in the line
6856 are treated literally.
6857 If the -r (--raw-mode) option is not specified, backslashes in the line
6859 are treated as quotations. If a backslash is at the end of the line, it
6860 is treated as a line continuation. When the built-in reads the next
6861 line, the PS2 variable is used as a prompt if the shell is interactive
6862 and the standard input is a terminal.
6863 The input line is subject to field splitting. The resulting words are
6865 assigned to variables in order. If there are more words than variables,
6866 the last variable is assigned all the remaining words (as if the words
6867 were not split). If the words are fewer than variables, the remaining
6868 variables are assigned empty strings.
6869 Options
6871 -A, --array
6872 Make the last variable an array. Instead of assigning a
6873 concatenation of the remaining words to a normal variable, the
6874 words are assigned to an array.
6875 -e, --line-editing
6877 Use line-editing to read the line.
6878 To use line-editing, all of the following conditions must also be
6880 met:
6881 • The shell is interactive.
6883 • The vi or emacs option is enabled.
6885 • The standard input and standard error are connected to a
6887 terminal.
6888 -P, --ps1
6890 Print the PS1 variable as a prompt before reading the (first) line
6891 if the shell is interactive and the standard input is a terminal.
6892 -p prompt, --prompt=prompt
6894 Print the specified prompt before reading the (first) line if the
6895 shell is interactive and the standard input is a terminal.
6896 -r, --raw-mode
6898 Don’t treat backslashes as quotations.
6899 Operands
6901 variables
6902 Names of variables to which input words are assigned.
6903 Exit status
6905 The exit status of the read built-in is zero unless there is any error.
6906 Note that the exit status is non-zero if an end of input is encountered
6908 before reading the entire line.
6909 Notes
6911 The read built-in is a semi-special built-in.
6912 The POSIX standard defines the -r option only: other options cannot be
6914 used in the POSIXly-correct mode.
6915 The PS1R and PS1S variables affect the behavior of line-editing if the
6917 PS1 prompt is used. The same for PS2.
6918
6920 The readonly built-in makes variables and functions read-only.
6921 Syntax
6923 • readonly [-pxX] [name[=value]...]
6924 • readonly -f[p] [name...]
6926 Description
6928 The readonly built-in is equivalent to the typeset built-in with the
6929 -gr option.
6930 Notes
6932 The readonly built-in is a special built-in.
6933 The POSIX standard defines the -p option only; other options cannot be
6935 used in the POSIXly-correct mode. The POSIX does not allow using the
6936 option together with operands.
6937
6939 The return built-in returns from a function or script.
6940 Syntax
6942 • return [-n] [exit_status]
6943 Description
6945 When executed without the -n (--no-return) option, one of the following
6946 happens:
6947 • If the shell is executing a function, the execution of the function
6949 is terminated.
6950 • If the dot built-in is executing a script, the execution of the
6952 script is terminated.
6953 • If the shell is executing a script during initialization, the
6955 execution of the script is terminated.
6956 • If the shell is executing a trap, the execution of the trap is
6958 terminated for the currently handled signal.
6959 • Otherwise, the shell exits unless it is interactive.
6961 When executed with the -n (--no-return) option, the built-in does
6963 nothing but return the specified exit_status.
6964 Options
6966 -n, --no-return
6967 Do not terminate a function, script, trap, or the shell.
6968 Operands
6970 exit_status
6971 The exit status of the built-in.
6972 The value must be a non-negative integer.
6974 If omitted, the exit status of the last executed command is used.
6976 (But when the shell is executing a trap, the exit status of the
6977 last command before the trap is used.)
6978 Exit status
6980 The exit status of the return built-in is defined by the exit_status
6981 operand. The exit status is used also as the exit status of the
6982 terminated function, script, or the shell.
6983 Notes
6985 The return built-in is a special built-in.
6986 The POSIX standard provides that the exit_status operand should be
6988 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
6989 an extension.
6990 In the POSIX standard, the behavior of the return built-in is defined
6992 only when the shell is executing a function or script.
6993 The POSIX standard defines no options for the return built-in; the
6995 built-in accepts no options in the POSIXly-correct mode.
6996
6998 The set built-in sets shell options and positional parameters.
6999 Syntax
7001 • set [options] [operands]
7002 • set -o
7004 • set +o
7006 The set built-in requires that all options precede operands. Any
7008 command line arguments after the first operand are all treated as
7009 operands.
7010 Description
7012 When executed without any command arguments, the built-in prints a list
7013 of all existing variables to the standard input in a form that can be
7014 reused as commands that will restore the variable definitions.
7015 When -o is the only command argument, the built-in prints a list of
7017 shell options with their current settings. When +o is the only command
7018 argument, the built-in prints commands that can be reused to restore
7019 the current shell option settings.
7020 In other cases, the built-in changes shell option settings and/or
7022 positional parameters.
7023 Options
7025 When one or more options are specified, the built-in enables or
7026 disables the shell options. A normal hyphen-prefixed option enables a
7027 shell option. An option that is prefixed with a plus (+) instead of a
7028 hyphen disables a shell option. For example, options -m, -o monitor,
7029 and --monitor enable the monitor option and options +m, +o monitor,
7030 ++monitor disable it.
7031 The name of a long option is case-insensitive and may include
7033 irrelevant non-alphanumeric characters, which are ignored. For example,
7034 options --le-comp-debug and --LeCompDebug are equivalent. If no is
7035 prepended to the name of a long option, the meaning is reversed. For
7036 example, --noallexport is equivalent to ++allexport and ++nonotify to
7037 --notify.
7038 An option can be specified in one of the following forms:
7040 • a long option e.g. --allexport
7042 • an -o option with a option name specified as the argument e.g. -o
7044 allexport
7045 • a single-character option e.g. -a
7047 Not all options can be specified as single-character options.
7049 The available options are:
7051 all-export (-a)
7053 When enabled, all variables are automatically exported when
7054 assigned.
7055 brace-expand
7057 This option enables brace expansion.
7058 case-glob
7060 (Enabled by default) When enabled, pattern matching is
7061 case-sensitive in pathname expansion.
7062 clobber (+C)
7064 (Enabled by default) When enabled, the > redirection behaves the
7065 same as the >| redirection.
7066 cur-async, cur-bg, cur-stop
7068 (Enabled by default) These options affect choice of the current job
7069 (cf. job ID).
7070 dot-glob
7072 When enabled, periods at the beginning of filenames are not treated
7073 specially in pathname expansion.
7074 emacs
7076 This option enables line-editing in the emacs mode.
7077 empty-last-field
7079 When enabled, field splitting does not remove the last field even
7080 if it is empty.
7081 err-exit (-e)
7083 When enabled, if a pipeline ends with a non-zero exit status, the
7084 shell immediately exits unless the following suppress condition is
7085 met:
7086 • the pipeline is a condition of an if command or while or until
7088 loop;
7089 • the pipeline is prefixed by !; or
7091 • the pipeline is a single compound command other than a subshell
7093 grouping.
7094 err-return
7096 This option is like the err-exit option, but the return built-in is
7097 executed instead of the shell exiting on a non-zero exit status.
7098 Unlike err-exit, the suppress condition does not apply inside a
7099 function, subshell grouping, or script file.
7100 exec (+n)
7102 (Enabled by default) Commands are actually executed only when this
7103 option is enabled. Otherwise, commands are just parsed and not
7104 executed. Disabling this option may be useful for syntax checking.
7105 In an interactive shell, this option is always assumed enabled.
7106 extended-glob
7108 This option enables extension in pathname expansion.
7109 for-local
7111 (Enabled by default) If a for loop is executed within a function,
7112 this option causes the iteration variable to be created as a local
7113 variable, even if the variable already exists globally. This option
7114 has no effect if the POSIXly-correct mode is active.
7115 glob (+f)
7117 (Enabled by default) This option enables pathname expansion.
7118 hash-on-def (-h)
7120 When a function is defined when this option is enabled, the shell
7121 immediately performs command path search for each command that
7122 appears in the function and caches the command’s full path.
7123 hist-space
7125 When enabled, command lines that start with a whitespace are not
7126 saved in command history.
7127 ignore-eof
7129 When enabled, an interactive shell does not exit when EOF (end of
7130 file) is input. This prevents the shell from exiting when you
7131 accidentally hit Ctrl-D.
7132 le-always-rp, le-comp-debug, le-conv-meta, le-no-conv-meta, le-predict,
7134 le-predict-empty, le-prompt-sp, le-visible-bell
7135 See shell options on line-editing.
7136 mark-dirs
7138 When enabled, resulting directory names are suffixed by a slash in
7139 pathname expansion.
7140 monitor (-m)
7142 This option enables job control. This option is enabled by default
7143 for an interactive shell.
7144 notify (-b)
7146 When the status of a job changes when this option is enabled, the
7147 shell immediately notifies at any time. This option overrides the
7148 notify-le option.
7149 notify-le
7151 This option is similar to the notify option, but the status change
7152 is notified only while the shell is waiting for input with
7153 line-editing.
7154 null-glob
7156 When enabled, in pathname expansion, patterns that do not match any
7157 pathname are removed from the command line rather than left as is.
7158 pipe-fail
7160 When enabled, the exit status of a pipeline is zero if and only if
7161 all the subcommands of the pipeline exit with an exit status of
7162 zero.
7163 posixly-correct
7165 This option enables the POSIXly-correct mode.
7166 trace-all
7168 (Enabled by default) When this option is disabled, the x-trace
7169 option is temporarily disabled while the shell is executing
7170 commands defined in the COMMAND_NOT_FOUND_HANDLER, PROMPT_COMMAND,
7171 or YASH_AFTER_CD variable.
7172 unset (+u)
7174 (Enabled by default) When enabled, an undefined parameter is
7175 expanded to an empty string in parameter expansion and treated as
7176 zero in arithmetic expansion. When disabled, expansion of an
7177 undefined parameter results in an error.
7178 verbose (-v)
7180 When enabled, the shell prints each command line to the standard
7181 error before parsing and executing it.
7182 vi
7184 This option enables line-editing in the vi mode. This option is
7185 enabled by default in an interactive shell if the standard input
7186 and error are both terminals.
7187 x-trace (-x)
7189 When enabled, the results of expansion are printed to the standard
7190 error for each simple command being executed. When printed, each
7191 line is prepended with an expansion result of the PS4 variable. See
7192 also the trace-all option.
7193 Operands
7195 If one or more operands are passed to the set built-in, current
7196 positional parameters are all removed and the operands are set as new
7197 positional parameters. If the -- separator (cf. syntax of command
7198 arguments) is passed, the positional parameters are set even when there
7199 are no operands, in which case new positional parameters will be
7200 nothing.
7201 Exit status
7203 The exit status of the set built-in is zero unless there is any error.
7204 Notes
7206 The set built-in is a special built-in.
7207 In the POSIX standard, available shell options are much limited. The
7209 standard does not define:
7210 • long options such as --allexport,
7212 • prepending no to negate an option,
7214 • using uppercase letters and/or non-alphanumeric characters in
7216 option names
7217 The options defined in the standard are:
7219 • -a, -o allexport
7221 • -e, -o errexit
7223 • -m, -o monitor
7225 • -C, -o noclobber
7227 • -n, -o noexec
7229 • -f, -o noglob
7231 • -b, -o notify
7233 • -u, -o nounset
7235 • -v, -o verbose
7237 • -x, -o xtrace
7239 • -h
7241 • -o ignoreeof
7243 • -o nolog
7245 • -o vi
7247 Yash does not support the nolog option, which prevents function
7249 definitions from being added to command history.
7250
7252 The shift built-in removes some positional parameters or array values.
7253 Syntax
7255 • shift [-A array] [count]
7256 Description
7258 The shift built-in removes the first count positional parameters or
7259 array values, where count is specified by the operand.
7260 Options
7262 -A array, --array=array
7263 Remove first count values of array instead of positional
7264 parameters.
7265 Operands
7267 count
7268 The number of positional parameters or array values to be removed.
7269 It is an error if the actual number of positional parameters or
7271 array values is less than count. If omitted, the default value is
7272 one. If negative, the last -count positional parameters or array
7273 values are removed instead of the first ones.
7274 Exit status
7276 The exit status of the shift built-in is zero unless there is any
7277 error.
7278 Notes
7280 The shift built-in is a special built-in.
7281 The number of positional parameters can be obtained with the # special
7283 parameter. The number of array values can be obtained with ${array[#]}.
7284 The POSIX standard defines no options for the shift built-in; the
7286 built-in accepts no options in the POSIXly-correct mode.
7287 Negative operands are not allowed in the POSIXly-correct mode.
7289
7291 The suspend built-in suspends the shell.
7292 Syntax
7294 • suspend [-f]
7295 Description
7297 The suspend built-in sends a SIGSTOP signal to all processes in the
7298 process group to which the shell process belongs. The signal suspends
7299 the processes (including the shell). The suspended processes resume
7300 when they receive a SIGCONT signal.
7301 If the shell is interactive and its process group ID is equal to the
7303 process ID of the session leader, the shell prints a warning message
7304 and refuses to send a signal unless the -f (--force) option is
7305 specified. (In such a case, there is no other job-controlling shell
7306 that can send a SIGCONT signal to resume the suspended shell, so the
7307 shell could never be resumed.)
7308 Options
7310 -f, --force
7311 Suppress warnings that would prevent the shell from sending a
7312 signal.
7313 Exit status
7315 The exit status is zero if the signal was successfully sent and
7316 non-zero otherwise.
7317 Notes
7319 The suspend built-in is a semi-special built-in. In the POSIX standard,
7320 it is defined as a command with unspecified behavior.
7321
7323 The test built-in evaluates an expression.
7324 Syntax
7326 • test expression
7327 • [ expression ]
7329 The test built-in does not distinguish options and operands; all
7331 command line arguments are interpreted as expression. If the built-in
7332 is executed with the name [, expression must be followed by ].
7333 Description
7335 The test built-in evaluates expression as a conditional expression that
7336 is made up of operators and operands described below. The exit status
7337 is 0 if the condition is true and 1 otherwise.
7338 The unary operators below test a file. If the operand file is a
7340 symbolic link, the file referred to by the link is tested (except for
7341 the -h and -L operators).
7342 -b file
7344 file is a block special file
7345 -c file
7347 file is a character special file
7348 -d file
7350 file is a directory
7351 -e file
7353 file exists
7354 -f file
7356 file is a regular file
7357 -G file
7359 file's group ID is same as the shell’s effective group ID
7360 -g file
7362 file's set-group-ID flag is set
7363 -h file
7365 same as -L
7366 -k file
7368 file's sticky bit is set
7369 -L file
7371 file is a symbolic link
7372 -N file
7374 file has not been accessed since last modified
7375 -O file
7377 file's user ID is same as the shell’s effective user ID
7378 -p file
7380 file is a FIFO (named pipe)
7381 -r file
7383 file is readable
7384 -S file
7386 file is a socket
7387 -s file
7389 file is not empty
7390 -u file
7392 file's set-user-ID flag is set
7393 -w file
7395 file is writable
7396 -x file
7398 file is executable
7399 The unary operator below tests a file descriptor:
7401 -t fd
7403 fd is associated with a terminal
7404 The unary operators below test a string:
7406 -n string
7408 string is not empty
7409 -z string
7411 string is empty
7412 The unary operator below tests a shell option:
7414 -o ?option
7416 option is a valid shell option name
7417 -o option
7419 option is a valid shell option name that is enabled
7420 The binary operators below compare files. Non-existing files are
7422 considered older than any existing files.
7423 file1 -nt file2
7425 file1 is newer than file2
7426 file1 -ot file2
7428 file1 is older than file2
7429 file1 -ef file2
7431 file1 is a hard link to file2
7432 The binary operators below compare strings:
7434 string1 = string2, string1 == string2
7436 string1 is the same string as string2
7437 string1 != string2
7439 string1 is not the same string as string2
7440 The binary operators below compare strings according to the alphabetic
7442 order in the current locale:
7443 string1 === string2
7445 string1 is equal to string2
7446 string1 !== string2
7448 string1 is not equal to string2
7449 string1 < string2
7451 string1 is less than string2
7452 string1 <= string2
7454 string1 is less than or equal to string2
7455 string1 > string2
7457 string1 is greater than string2
7458 string1 >= string2
7460 string1 is greater than or equal to string2
7461 The binary operator below performs pattern matching:
7463 string =~ pattern
7465 extended regular expression pattern matches (part of) string
7466 The binary operators below compare integers:
7468 v1 -eq v2
7470 v1 is equal to v2
7471 v1 -ne v2
7473 v1 is not equal to v2
7474 v1 -gt v2
7476 v1 is greater than v2
7477 v1 -ge v2
7479 v1 is greater than or equal to v2
7480 v1 -lt v2
7482 v1 is less than v2
7483 v1 -le v2
7485 v1 is less than or equal to v2
7486 The binary operators below compare version numbers:
7488 v1 -veq v2
7490 v1 is equal to v2
7491 v1 -vne v2
7493 v1 is not equal to v2
7494 v1 -vgt v2
7496 v1 is greater than v2
7497 v1 -vge v2
7499 v1 is greater than or equal to v2
7500 v1 -vlt v2
7502 v1 is less than v2
7503 v1 -vle v2
7505 v1 is less than or equal to v2
7506 The operators below can be used to make complex expressions:
7508 ! expression
7510 negate (reverse) the result
7511 ( expression )
7513 change operator precedence
7514 expression1 -a expression2
7516 logical conjunction (and)
7517 expression1 -o expression2
7519 logical disjunction (or)
7520 If the expression is a single word without operators, the -n operator
7522 is assumed. An empty expression evaluates to false.
7523 Comparison of version numbers
7525 Comparison of version numbers is similar to comparison of strings
7526 in alphabetic order. The differences are:
7527 • Adjacent digits are treated as an integer. Integers are
7529 compared in mathematical order rather than alphabetic order.
7530 • Digits are considered larger than any non-digit characters.
7532 For example, version numbers 0.1.2-3 and 00.001.02-3 are equal and
7534 0.2.1 is smaller than 0.10.0.
7535 Exit status
7537 The exit status of the test built-in is 0 if expression is true and 1
7538 otherwise. The exit status is 2 if expression cannot be evaluated
7539 because of a syntax error or any other reasons.
7540 Notes
7542 Complex expressions may cause confusion and should be avoided. Use the
7543 shell’s compound commands. For example, [ 1 -eq 1 ] && [ -t = 1 ] && !
7544 [ foo ] is preferred over [ 1 -eq 1 -a -t = 1 -a ! foo ].
7545 The POSIX standard provides that the exit status should be larger than
7547 1 on error. The POSIX standard does not define the following operators:
7548 -G, -k, -N, -O, -nt, -ot, -ef, ==, ===, !==, <, <=, >, >=, =~, -veq,
7549 -vne, -vgt, -vge, -vlt, and -vle. POSIX neither specifies -o as a unary
7550 operator.
7551
7553 The times built-in prints CPU time usage.
7554 Syntax
7556 • times
7557 Description
7559 The times built-in prints the CPU times consumed by the shell process
7560 and its child processes to the standard output.
7561 The built-in prints two lines: the first line shows the CPU time of the
7563 shell process and the second one that of its child processes (not
7564 including those which have not terminated). Each line shows the CPU
7565 times consumed in the user and system mode.
7566 Exit status
7568 The exit status of the times built-in is zero unless there is any
7569 error.
7570 Notes
7572 The times built-in is a special built-in.
7573
7575 The trap built-in sets or prints signal handlers.
7576 Syntax
7578 • trap
7579 • trap action signal...
7581 • trap signal_number [signal...]
7583 • trap -p [signal...]
7585 Description
7587 The trap built-in sets or prints actions that are taken when the shell
7588 receives signals. (Those actions are called traps.)
7589 When executed with action and one or more signals, the built-in sets
7591 the traps for signals to action. If the shell receives one of the
7592 signals, the action will be taken.
7593 If the first operand is signal_number instead of action, the built-in
7595 resets the traps for signal_number and signals as if action was -.
7596 When executed with the -p (--print) option or with no operands, the
7598 built-in prints currently set traps to the standard output in a format
7599 that can be executed as commands that restore the current traps. If one
7600 or more signals are specified, only those signals are printed.
7601 Otherwise, all signals with non-default actions are printed. (In some
7602 situations, however, the built-in may print previous trap settings
7603 instead of the current. See notes below.)
7604 Options
7606 -p, --print
7607 Print current trap settings.
7608 Operands
7610 action
7611 An action that will be taken when signal is received.
7612 If action is a single hyphen (-), the action is reset to the
7614 default action that is defined by the operating system. If action
7615 is an empty string, the signal is ignored on receipt. Otherwise,
7616 action is treated as a command string: the string is parsed and
7617 executed as commands when the signal is received. (If a signal is
7618 received while a command is being executed, the action is taken
7619 just after the command finishes.)
7620 signal
7622 The number or name of a signal.
7623 If signal is number 0 or name EXIT, it is treated as a special
7625 imaginary signal that is always received when the shell exits. The
7626 action set for this signal is taken when the shell exits normally.
7627 signal_number
7629 This is like signal, but must be a number.
7630 Exit status
7632 The exit status of the trap built-in is zero unless there is any error.
7633 Notes
7635 The trap built-in is a special built-in.
7636 The POSIX standard defines no options for the trap built-in; the
7638 built-in accepts no options in the POSIXly-correct mode.
7639 The POSIX standard requires that signal names must be specified without
7641 the SIG-prefix, like INT and QUIT. As an extension, yash accepts
7642 SIG-prefixed names like SIGINT and SIGQUIT and treats signal names
7643 case-insensitively.
7644 Reusing output of the built-in
7646 Output of the trap built-in can be saved in a variable, which can
7647 be later executed by the eval built-in to restore the traps.
7648 saved_traps=$(trap)
7650 trap '...' INT
7651 eval "$saved_traps"
7652 There are some tricks behind the scenes to allow this idiom. You
7654 use a command substitution to save the output of the trap built-in
7655 in the variable. The command substitution is executed in a
7656 subshell. The subshell resets all traps (except ignored ones) at
7657 the beginning of itself. This seemingly would result in (almost)
7658 empty output from the built-in that would fail to restore the traps
7659 as expected.
7660 To avoid that pitfall, POSIX requires the shell to follow one of
7662 the two options below:
7663 • If a command substitution just contains a single trap built-in,
7665 traps should not be reset when the subshell is started to
7666 execute the built-in; or
7667 • A subshell always resets the traps but remembers the previous
7669 traps. If the trap built-in is executed in the subshell but no
7670 other trap built-in has been executed to modify traps in the
7671 subshell, then the built-in should print the remembered traps.
7672 Yash obeys the second.
7674
7676 The true built-in does nothing successfully.
7677 Syntax
7679 • true
7680 Description
7682 The true built-in does nothing. Any command line arguments are ignored.
7683 Exit status
7685 The exit status of the true built-in is zero.
7686 Notes
7688 The true built-in is a semi-special built-in.
7689 The true and colon built-ins have the same effect, but true is a
7691 semi-special built-in while colon is a special.
7692
7694 The type built-in identifies a command.
7695 Syntax
7697 • type [-abefkp] [command...]
7698 Description
7700 The type built-in is equivalent to the command built-in with the -V
7701 option.
7702 Notes
7704 The POSIX standard does not define the relation between the type and
7705 command built-ins. The standard does not define options for the type
7706 built-in.
7707 At least one command operand must be specified in the POSIXly-correct
7709 mode.
7710 The type built-in is a semi-special built-in.
7712
7714 The typeset built-in prints or sets variables or functions.
7715 Syntax
7717 • typeset [-gprxX] [variable[=value]...]
7718 • typeset -f[pr] [function...]
7720 Description
7722 If executed without the -f (--functions) option, the typeset built-in
7723 prints or sets variables to the standard output. Otherwise, it prints
7724 or sets functions.
7725 If executed with the -p (--print) option, the built-in prints the
7727 variables or functions specified by operands. Without the option, it
7728 sets variables or functions. If no operands are specified, it prints
7729 all existing variables or functions, regardless of whether the -p
7730 (--print) option is specified.
7731 Options
7733 -f, --functions
7734 Print or set functions rather than variables.
7735 -g, --global
7737 When setting a new variable, the variable will be a global variable
7738 if this option is specified. Without this option, the variable
7739 would be a local variable.
7740 When printing variables, all existing variables including global
7742 variables are printed if this option is specified. Without this
7743 option, only local variables are printed.
7744 -p, --print
7746 Print variables or functions in a form that can be parsed and
7747 executed as commands that will restore the currently set variables
7748 or functions.
7749 -r, --readonly
7751 When setting variables or functions, make them read-only.
7752 When printing variables or functions, print read-only variables or
7754 functions only.
7755 -x, --export
7757 When setting variables, mark them for export, so that they will be
7758 exported to external commands.
7759 When printing variables, print exported variables only.
7761 -X, --unexport
7763 When setting variables, cancel exportation of the variables.
7764 Operands
7766 variable (without value)
7767 The name of a variable that is to be set or printed.
7768 Without the -p (--print) option, the variable is defined (if not
7770 yet defined) but its value is not set nor changed. Variables that
7771 are defined without values are treated as unset in parameter
7772 expansion.
7773 variable=value
7775 The name of a variable and its new value.
7776 The value is assigned to the variable (regardless of the -p
7778 (--print) option).
7779 function
7781 The name of an existing function that is to be set or printed.
7782 Exit status
7784 The exit status of the typeset built-in is zero unless there is any
7785 error.
7786 Notes
7788 A global variable cannot be newly defined if a local variable has
7789 already been defined with the same name. The local variable will be set
7790 regardless of the -g (--global) option.
7791 The typeset built-in is a semi-special built-in. In the POSIX standard,
7793 it is defined as a command with unspecified behavior.
7794 The export and readonly built-ins are equivalent to the typeset
7796 built-in with the -gx and -gr options, respectively. The local built-in
7797 is equivalent to the typeset built-in except that the -f (--functions)
7798 and -g (--global) options cannot be used.
7799
7801 The ulimit built-in sets or prints a resource limit.
7802 Syntax
7804 • ulimit -a [-H|-S]
7805 • ulimit [-H|-S] [-efilnqrstuvx] [limit]
7807 Description
7809 The ulimit built-in sets or prints a resource limit.
7810 If executed with the -a (--all) option, the built-in prints the current
7812 limits for all resource types. Otherwise, it sets or prints the limit
7813 of a single resource type. The resource type can be specified by the
7814 options listed below. The resource limits will affect the current shell
7815 process and all commands invoked from the shell.
7816 Each resource type has two limit values: the hard and soft limit. You
7818 can change a soft limit freely as long as it does not exceed the hard
7819 limit. You can decrease a hard limit but cannot increase it without a
7820 proper permission.
7821 When the -H (--hard) or -S (--soft) option is specified, the built-in
7823 sets or prints the hard or soft limit, respectively. If neither of the
7824 options is specified, the built-in sets both the hard and soft limit or
7825 prints the soft limit.
7826 Options
7828 -H, --hard
7829 Set or print a hard limit.
7830 -S, --soft
7832 Set or print a soft limit.
7833 -a, --all
7835 Print all current limit settings.
7836 The following options specify the type of resources. If none of them is
7838 specified, -f is the default. The types of resources that can be set
7839 depend on the operating system.
7840 -c, --core
7842 Maximum size of core files created (in 512-byte blocks)
7843 -d, --data
7845 Maximum size of a process’s data segment (in kilobytes)
7846 -e, --nice
7848 Maximum scheduling priority (‘nice’)
7849 -f, --fsize
7851 Maximum size of files created by a process (in 512-byte blocks)
7852 -i, --sigpending
7854 Maximum number of pending signals
7855 -l, --memlock
7857 Maximum memory size that can be locked into RAM (in kilobytes)
7858 -m, --rss
7860 Maximum size of a process’s resident set (in kilobytes)
7861 -n, --nofile
7863 Maximum file descriptor + 1
7864 -q, --msgqueue
7866 Maximum size of POSIX message queues
7867 -r, --rtprio
7869 Maximum real-time scheduling priority
7870 -s, --stack
7872 Maximum size of a process’s stack (in kilobytes)
7873 -t, --cpu
7875 Maximum CPU time that can be used by a process (in seconds)
7876 -u, --nproc
7878 Maximum number of processes for a user
7879 -v, --as
7881 Maximum size of memory used by a process (in kilobytes)
7882 -x, --locks
7884 Maximum number of file locks
7885 Operands
7887 limit
7888 A limit to be set.
7889 The value must be a non-negative integer or one of hard, soft, and
7891 unlimited. If value is hard or soft, the new limit is set to the
7892 current hard or soft limit. If limit is not specified, the current
7893 limit is printed.
7894 Exit status
7896 The exit status of the ulimit built-in is zero unless there is any
7897 error.
7898 Notes
7900 The POSIX standard defines no options other than -f. It neither defines
7901 hard, soft, or unlimited for limit values.
7902 The ulimit built-in is a semi-special built-in.
7904
7906 The umask built-in sets or prints the file mode creation mask.
7907 Syntax
7909 • umask mask
7910 • umask [-S]
7912 Description
7914 If executed without the mask operand, the built-in prints the current
7915 file mode creation mask of the shell to the standard output in a form
7916 that can later be used as mask to restore the current mask.
7917 Otherwise, the built-in sets the file mode creation mask to mask.
7919 Options
7921 -S, --symbolic
7922 Print in the symbolic form instead of the octal integer form.
7923 Operands
7925 mask
7926 The new file mode creation mask either in the symbolic or octal
7927 integer form.
7928 Octal integer form
7930 In the octal integer form, the mask is specified as a non-negative
7931 octal integer that is the sum of the following permissions:
7932 0400
7934 read by owner
7935 0200
7937 write by owner
7938 0100
7940 execute/search by owner
7941 0040
7943 read by group
7944 0020
7946 write by group
7947 0010
7949 execute/search by group
7950 0004
7952 read by others
7953 0002
7955 write by others
7956 0001
7958 execute/search by others
7959 Symbolic form
7961 In the symbolic form, the mask is specified as a symbolic
7962 expression that denotes permissions that are not included in the
7963 mask.
7964 The entire expression is one or more clauses separated by comma. A
7966 clause is a sequence of whos followed by one or more actions.
7967 A who is one of:
7969 u
7971 owner
7972 g
7974 group
7975 o
7977 others
7978 a
7980 all of owner, group, and others
7981 An empty sequence of whos is equivalent to who a.
7983 An action is an operator followed by permission. An operator is one
7985 of:
7986 =
7988 set who's permission to permission
7989 +
7991 add permission to who's permission
7992 -
7994 remove permission from who's permission
7995 and permission is one of:
7997 r
7999 read
8000 w
8002 write
8003 x
8005 execute/search
8006 X
8008 execute/search (only if some user already has execute/search
8009 permission)
8010 s
8012 set-user-ID and set-group-ID
8013 u
8015 user’s current permissions
8016 g
8018 group’s current permissions
8019 o
8021 others' current permissions
8022 but more than one of r, w, x, X, and s can be specified after a
8024 single operand.
8025 For example, the command umask u=rwx,go+r-w
8027 • unmasks the user’s read, write, and execute/search permissions;
8029 • unmasks the group’s and others' read permission; and
8031 • masks the group’s and others' write permission.
8033 Exit status
8035 The exit status of the umask built-in is zero unless there is any
8036 error.
8037 Notes
8039 The umask built-in is a semi-special built-in.
8040 The POSIX standard does not require the default output format (used
8042 when the -S option is not specified) to be the octal integer form.
8043
8045 The unalias built-in undefines aliases.
8046 Syntax
8048 • unalias name...
8049 • unalias -a
8051 Description
8053 The unalias built-in removes the definition of the aliases specified by
8054 operands.
8055 Options
8057 -a, --all
8058 Undefine all aliases.
8059 Operands
8061 name
8062 The name of an alias to be undefined.
8063 Exit status
8065 The exit status of the unalias built-in is zero unless there is any
8066 error. It is an error to specify the name of a non-existing alias as
8067 name.
8068 Notes
8070 The unalias built-in is a semi-special built-in.
8071
8073 The unset built-in undefines variables or functions.
8074 Syntax
8076 • unset [-fv] [name...]
8077 Description
8079 The unset built-in removes the definition of the variables or functions
8080 specified by operands.
8081 It is not an error if any of the specified variables or functions do
8083 not exist; they are silently ignored.
8084 Options
8086 -f, --functions
8087 Undefine functions.
8088 -v, --variables
8090 Undefine variables.
8091 These options are mutually exclusive: only the last specified one is
8093 effective. If neither is specified, -v is assumed.
8094 Operands
8096 name
8097 The name of a variable or function to be undefined.
8098 Exit status
8100 The exit status of the unset built-in is zero unless there is any
8101 error.
8102 Notes
8104 The unset built-in is a special built-in.
8105 Although yash does not do so, the POSIX standard allows removing a
8107 function if neither of the -f and -v options is specified and the
8108 specified variable does not exist.
8109 At least one name operand must be specified in the POSIXly-correct
8111 mode.
8112
8114 The wait built-in waits for jobs to terminate.
8115 Syntax
8117 • wait [job...]
8118 Description
8120 The wait built-in waits for background jobs to terminate. If job
8121 control is enabled, stopped jobs are considered as terminated.
8122 The built-in can be used to wait for asynchronous commands if job
8124 control is disabled.
8125 If the shell receives a signal while the built-in is waiting and if a
8127 trap has been set for the signal, then the trap is executed and the
8128 built-in immediately finishes (without waiting for the jobs). If the
8129 shell receives a SIGINT signal when job control is enabled, the
8130 built-in aborts waiting.
8131 If the shell is interactive, job-controlling, and not in the
8133 POSIXly-correct mode, the job status is printed when the job is
8134 terminated or stopped.
8135 Operands
8137 job
8138 The job ID of the job or the process ID of a process in the job.
8139 If no jobs are specified, the built-in waits for all existing jobs.
8141 If the specified job does not exist, the job is considered to have
8143 terminated with the exit status of 127.
8144 Exit status
8146 If no jobs were specified and the built-in successfully waited for all
8147 the jobs, the exit status is zero. If one or more jobs were specified,
8148 the exit status is that of the last job.
8149 If the built-in was aborted by a signal, the exit status is an integer
8151 (> 128) that denotes the signal. If there was any other error, the exit
8152 status is between 1 and 126 (inclusive).
8153 Notes
8155 The wait built-in is a semi-special built-in.
8156 The process ID of the last process of a job can be obtained by the !
8158 special parameter. You can use the jobs built-in as well to obtain
8159 process IDs of job processes.
8160
8162 Yuki Watanabe <magicant@users.osdn.me>
8163 Author.
8164 2.53 2022-08-23 YASH(1)