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 Each word is assigned as a local variable except in the
467 POSIXly-correct mode. If the expansion of the words yielded no
468 words as a result, the commands are not executed at all.
469 The exit status of a for loop is that of the last executed command.
471 The exit status is zero if the commands are not empty and not
472 executed at all. If the commands are empty, the exit status is that
473 of the last executed command before the for loop.
474 If the variable is read-only, the execution of the for loop is
476 interrupted and the exit status will be non-zero.
477 Case command
479 The case command performs a pattern matching to select commands to
480 execute.
481 Case command syntax
483 case word in caseitem... esac
484 Case item syntax
486 (patterns) command...;;
487 The word between the case and in tokens must be exactly one word.
489 The word is not treated as a keyword, but you need to quote
490 separator characters (such as & and |) to include them as part of
491 the word. Between the in and esac tokens you can put any number of
492 case items (may be none). You can omit the first ( token of a case
493 item and the last ;; token before the esac token. If the last
494 command of a case item is terminated by a semicolon, you can omit
495 the semicolon as well. The commands in a case item may be empty.
496 The patterns in a case item are one or more tokens each separated
498 by a | token.
499 The execution of a case command starts with subjecting the word to
501 the four expansions. Next, the following steps are taken for each
502 case item (in the order of appearance):
503 1. For each word in the patterns, expand the word in the same
505 manner as the word and test if the expanded pattern matches the
506 expanded word. (If a pattern is found that matches the word,
507 the remaining patterns are not expanded nor tested, so some of
508 the patterns may not be expanded. Yash expands and tests the
509 patterns in the order of appearance, but it may not be the case
510 for other shells.)
511 2. If one of the patterns was found to match the word in the
513 previous step, the commands in this case item are executed and
514 the execution of the whole case item ends. Otherwise, proceed
515 to the next case item.
516 The exit status of a case command is that of the commands executed.
518 The exit status is zero if no commands were executed, that is,
519 there were no case items, no matching pattern was found, or no
520 commands were associated with the matching pattern.
521 In the POSIXly-correct mode, the first pattern in a case item
523 cannot be esac (even if you do not omit the ( token).
524 Double-bracket command
526 The double-bracket command is a syntactic construct that works
527 similarly to the test built-in. It expands and evaluates the words
528 between the brackets.
529 Double-bracket command syntax
531 [[ expression ]]
532 The expression can be a single primary or combination of primaries
534 and operators. The expression syntax is parsed when the command is
535 parsed, not executed. Operators (either primary or non-primary)
536 must not be quoted, or it will be parsed as a normal word.
537 When the command is executed, operand words are subjected to the
539 four expansions, but not brace expansion, field splitting, or
540 pathname expansion.
541 In the double-bracket command, the following primaries from the
543 test built-in can be used:
544 Unary primaries
546 -b, -c, -d, -e, -f, -G, -g, -h, -k, -L, -N, -n, -O, -o, -p, -r,
547 -S, -s, -t, -u, -w, -x, -z
548 Binary primaries
550 -ef, -eq, -ge, -gt, -le, -lt, -ne, -nt, -ot, -veq, -vge, -vgt,
551 -vle, -vlt, -vne, ===, !==, =~, <, >
552 Additionally, some binary primaries can be used to compare strings,
554 which works slightly differently from those for the test built-in:
555 The = primary treats the right-hand-side operand word as a pattern
556 and tests if it matches the left-hand-side operand word. The ==
557 primary is the same as =. The != primary is negation of the =
558 primary (reverse result).
559 The operand word of a primary must be quoted if it is ]] or can be
561 confused with another primary operator.
562 Note
564 More primaries may be added in future versions of the shell.
565 You should quote any words that start with a hyphen.
566 Note
568 The <= and >= binary primaries cannot be used in the
569 double-bracket command because it cannot be parsed correctly in
570 the shell grammar.
571 The following operands (listed in the descending order of
573 precedence) can be used to combine primaries:
574 ( expression )
576 A pair of parentheses change operator precedence.
577 ! expression
579 An exclamation mark negates (reverses) the result.
580 expression && expression
582 A double ampersand represents logical conjugation (the “and”
583 operation). The entire expression is true if and only if the
584 operand expressions are both true. The left-hand-side
585 expression is first expanded and tested. The right-hand-side is
586 expanded only if the left-hand-side is true.
587 expression || expression
589 A double vertical line represents logical conjugation (the “or”
590 operation). The entire expression is false if and only if the
591 operand expressions are both false. The left-hand-side
592 expression is first expanded and tested. The right-hand-side is
593 expanded only if the left-hand-side is false.
594 Note
596 Unlike the test built-in, neither -a nor -o can be used as a
597 binary operator in the double-bracket command.
598 The exit status of the double-bracket command is 0 if expression is
600 true, 1 if false, and 2 if it cannot be evaluated because of
601 expansion error or any other reasons.
602 Note
604 The double-bracket command is also supported in bash, ksh,
605 mksh, and zsh, but not defined in the POSIX standard. The
606 behavior slightly differs between the shells. The test built-in
607 should be preferred over the double-bracket command for maximum
608 portability.
609 Function definition
611 The function definition command defines a function.
612 Function definition syntax
614 funcname ( ) compound_command
615 function funcname compound_command
617 function funcname ( ) compound_command
619 In the first syntax without the function keyword, funcname cannot
621 contain any special characters such as semicolons and quotation marks.
622 In the second and third syntax, which cannot be used in the
623 POSIXly-correct mode, funcname is subjected to the four expansions when
624 executed. In the POSIXly-correct mode, funcname is limited to a
625 portable (ASCII-only) name.
626 When a function definition command is executed, a function whose name
628 is funcname is defined with its body being compound_command.
629 A function definition command cannot be directly redirected. Any
631 redirections that follow a function definition are associated with
632 compound_command rather than the whole function definition command. In
633 func() { cat; } >/dev/null, for example, it is not func() { cat; } but
634 { cat; } that is redirected.
635 The exit status of a function definition is zero if the function was
637 defined without errors, and non-zero otherwise.
638
640 Parameters are string values that are expanded in parameter expansion.
641 There are three types of parameters: positional parameters, special
642 parameters and variables.
643 Positional parameters
645 Positional parameters are parameters that are identified by natural
646 numbers. If there are three positional parameters, for example, they
647 are identified as 1, 2, and 3. You can obtain the number of positional
648 parameters by the # special parameter. The * and @ special parameters
649 are expanded to all positional parameters.
650 Positional parameters are initialized from the shell’s command line
652 arguments when the shell is started (see Command line arguments). In
653 the initialization, the order of the operands are preserved as the
654 order of the positional parameters.
655 When the shell executes a function call, positional parameters are
657 changed to the arguments to the function call so that you can access
658 the arguments while the function is being executed. Positional
659 parameters are restored to the original values when the execution of
660 the function is finished.
661 Positional parameters can be manipulated by built-in commands like set
663 and shift.
664 Note that 0 is not a positional parameter but a special parameter.
666 Special parameters
668 Special parameters are parameters each identified by a single symbol.
669 They cannot be directly assigned to by the user.
670 Yash provides the following special parameters:
672 0
674 The name of the shell executable file or the script file that was
675 specified in the invocation of the shell.
676 #
678 The number of current positional parameters. The value is a
679 non-negative integer.
680 $
682 The process ID of the shell. The value is a positive integer and is
683 never changed even in subshells.
684 -
686 Currently enabled shell options. The value is a concatenation of
687 alphabet characters that are the names of currently enabled
688 single-character options that can be specified in shell invocation.
689 The value reflects changes of enabled options when you enable or
690 disable options using the set built-in.
691 ?
693 The exit status of the last executed pipeline. The value is a
694 non-negative integer.
695 !
697 The process ID of the last executed asynchronous list.
698 *
700 This special parameter represents the whole positional parameters.
701 When there is no positional parameters, the value of this special
702 parameter is the empty string. When there is more than one
703 positional parameter, the value is a concatenation of all the
704 positional parameters, each of which is separated as follows:
705 · If the IFS variable exists and its value is not empty,
707 positional parameters are each separated by the first character
708 of the value of the IFS variable.
709 · If the IFS variable exists and has an empty value, positional
711 parameters are just concatenated without any separator.
712 · If the IFS variable does not exist, positional parameters are
714 each separated by a space character.
715 If field-splitting is applied to an expansion result of this
717 parameter, the value is first split into the original positional
718 parameters and then further split depending on the current IFS
719 variable. The first splitting is performed even if the IFS variable
720 is empty.
721 @
723 This special parameter represents the whole positional parameters
724 like the * special parameter above. The difference between the two
725 is the results of expansion that occurs between a pair of
726 double-quotation marks. If the @ special parameter is expanded
727 inside double-quotations, the result is field-split into the exact
728 positional parameter values. If there are no positional parameters,
729 the expansion yields no word rather than an empty word. (Even if
730 the expansion is double-quoted, the result is not always a single
731 word.)
732 · When there are no positional parameters, the command words echo
734 1 "$@" 2 are expanded to the three words echo, 1, and 2.
735 · When positional parameters are the three words 1, 2 2, and 3,
737 the command words echo "$@" are expanded to the four words
738 echo, 1, 2 2, and 3, and the words echo "a$@b" to the four
739 words echo, a1, 2 2, and 3b.
740 Variables
742 Variables are parameters the user can assign values to. Each variable
743 has a name that identifies it and a value that defines the results of
744 expansion.
745 A variable name is composed of one or more alphanumeric characters and
747 underscores (_). A name cannot start with a digit. Other characters may
748 be used in a name depending on internationalization support of your
749 environment.
750 Variables that are exported to external commands are called environment
752 variables. They are passed to all external commands the shell invokes.
753 Variables passed to the shell in invocation will be automatically
754 exported.
755 You can assign to variables by a simple command as well as the typeset
757 built-in. You can remove variables by using the unset built-in.
758 Variables used by the shell
760 The following variables are used by the shell for special purposes.
761 CDPATH
763 This variable is used by the cd built-in to find a destination
764 directory.
765 COLUMNS
767 This variable specifies the width (the number of character
768 columns) of the terminal screen. The value affects the display
769 of line-editing.
770 COMMAND_NOT_FOUND_HANDLER
772 When the shell cannot find a command to be executed, the value
773 of this variable is interpreted and executed instead. You can
774 override the shell’s error handling behavior with this
775 variable. See Execution of simple commands for detail.
776 This feature is disabled in the POSIXly-correct mode.
778 DIRSTACK
780 This array variable is used by the shell to store the directory
781 stack contents. If you modify the value of this variable, the
782 directory stack may be corrupted.
783 ECHO_STYLE
785 This variable specifies the behavior of the echo built-in.
786 ENV
788 When an interactive shell is started in the POSIXly-correct
789 mode, the value of this variable is used to find the
790 initialization file. See Initialization of yash.
791 FCEDIT
793 This variable specifies an editor program used to edit command
794 lines during execution of the fc built-in.
795 HANDLED
797 This variable can be set in the command-not-found handler to
798 tell the shell not to produce a further error message. See
799 Execution of simple commands for detail.
800 HISTFILE
802 This variable specifies the pathname of the file to save the
803 command history in.
804 HISTRMDUP
806 This variable specifies the number of command history items to
807 be checked for duplication. When the shell is adding a new
808 history item to the command history, if some of the most recent
809 n items have the same contents as the new one, then the
810 duplicate existing items are removed from the history before
811 the new one is added, where n is the value of this variable.
812 If the value of this variable is 1, for example, the most
814 recent item is removed when a new item that have the same
815 contents is added.
816 Items older than the nth recent item are not removed. No items
818 are removed if the value of this variable is 0. All items are
819 subject to removal if the variable value is greater than or
820 equal to the value of the HISTSIZE variable.
821 HISTSIZE
823 This variable specifies the maximum number of items in the
824 command history.
825 HOME
827 This variable specifies the pathname of the user’s home
828 directory and affects results of tilde expansion and cd
829 built-in.
830 IFS
832 This variable specifies separators used in field splitting. The
833 variable value is initialized to the three characters of a
834 space, a tab, and a newline when the shell is started.
835 LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY,
837 LC_NUMERIC, LC_TIME
838 These variables specify a locale in which the shell runs. The
839 shell chooses the file input/output encoding, the error message
840 language, etc. according to the locale specified.
841 Unless the shell is interactive and not in the POSIXly-correct
843 mode, the value of the LC_CTYPE variable is considered only
844 when the shell is started. Once the shell has been initialized,
845 changing the value of LC_CTYPE will have no effect on the
846 shell’s behavior.
847 LINENO
849 The value of this variable is automatically set to the line
850 number in which the currently executed command appears in the
851 file.
852 In the interactive shell, the line number is reset to 1 each
854 time the shell reads and executes a command.
855 If you assign to or remove this variable, it will no longer
857 provide line numbers.
858 LINES
860 This variable specifies the height (the number of character
861 lines) of the terminal screen. The value affects the display of
862 line-editing.
863 MAIL
865 This variable specifies the pathname of a file that is checked
866 in mail checking.
867 MAILCHECK
869 This variable specifies how often the shell should do mail
870 checking. The value has to be specified as a positive integer
871 in seconds. The value is initialized to the default value of
872 600 when the shell is started.
873 MAILPATH
875 This variable specifies the pathnames of files that are checked
876 in mail checking.
877 NLSPATH
879 The POSIX standard prescribes that the value of this variable
880 specifies pathname templates of locale-dependent message data
881 files, but yash does not use it.
882 OLDPWD
884 This variable is set to the previous working directory path
885 when you change the working directory by using the cd or other
886 built-ins. This variable is exported by default.
887 OPTARG
889 When the getopts built-in parses an option that takes an
890 argument, the argument value is assigned to this variable.
891 OPTIND
893 The value of this variable specifies the index of an option
894 that is to be parsed by the next getopts built-in execution.
895 This variable is initialized to 1 when the shell is started.
896 PATH
898 This variable specifies paths that are searched for a command
899 in command search.
900 PPID
902 The value of this variable is the process ID of the shell’s
903 parent process, which is a positive integer. This variable is
904 initialized when the shell is started. The value is not changed
905 when the shell makes a new subshell.
906 PROMPT_COMMAND
908 The shell interprets and executes the value of this variable
909 before printing each command prompt if the shell is interactive
910 and not in the POSIXly-correct mode. This behavior is
911 equivalent to executing the command eval -i --
912 "${PROMPT_COMMAND-}" before each command prompt, but its exit
913 status does not affect the expansion of the ? special
914 parameter in the next command.
915 PS1
917 This variable specifies the main command prompt string printed
918 by an interactive shell. See Prompts for the format of the
919 variable value. The value is initialized to either $ or #
920 depending on whether the effective user ID of the shell process
921 is zero or not.
922 PS1R
924 This variable specifies the auxiliary prompt string printed to
925 the right of the cursor when you input a command line to an
926 interactive shell. See Prompts for the format of the variable
927 value.
928 PS1S
930 This variable specifies the font style of command strings you
931 enter to an interactive shell. See Prompts for the format of
932 the variable value.
933 PS2
935 This variable is like the PS1 variable, but it is used for the
936 second and following lines of a command that is longer than one
937 line. See Prompts for the format of the variable value. The
938 value is initialized to > when the shell is started.
939 PS2R
941 This variable is like the PS1R variable, but it is used when
942 PS2 is used. See Prompts for the format of the variable value.
943 PS2S
945 This variable is like the PS1S variable, but it is used when
946 PS2 is used. See Prompts for the format of the variable value.
947 PS4
949 The value of this variable is printed before each command trace
950 output when the xtrace option is enabled. The value is subject
951 to parameter expansion, command substitution, arithmetic
952 expansion. You can also use backslash notations if the shell is
953 not in the POSIXly-correct mode. The value is initialized to +
954 when the shell is started.
955 PS4S
957 This variable is like the PS1S variable, but it is used when
958 PS4 is used. You can use this variable to modify font style of
959 command trace output.
960 PWD
962 The value of this variable is the pathname of the current
963 working directory. The value is set when the shell is started
964 and reset each time the working directory is changed by the cd
965 or other built-ins. This variable is exported by default.
966 RANDOM
968 You can use this variable to get random numbers. The value of
969 this variable is a uniformly distributed random integer between
970 0 and 32767 (inclusive). You will get a different number each
971 time the variable is expanded.
972 You can set the “seed” of random numbers by assigning a
974 non-negative integer to the variable.
975 If you remove this variable, it will no longer work as a random
977 number generator. If the shell was invoked in the
978 POSIXly-correct mode, this variable does not work as a random
979 number generator.
980 TERM
982 This variable specifies the type of the terminal in which the
983 shell is running. The value affects the behavior of
984 line-editing. This variable has to be exported to take effect.
985 YASH_AFTER_CD
987 The shell interprets and executes the value of this variable
988 after each time the shell’s working directory is changed by the
989 cd or other built-ins. This behavior is equivalent to executing
990 the command eval -i -- "${YASH_AFTER_CD-}" after the directory
991 was changed.
992 YASH_LOADPATH
994 This variable specifies directories the dot built-in searches
995 for a script file. More than one directory can be specified by
996 separating them by colons like the PATH variable. When the
997 shell is started, this variable is initialized to the pathname
998 of the directory where common script files are installed.
999 YASH_LE_TIMEOUT
1001 This variable specifies how long the shell should wait for a
1002 next possible input from the terminal when it encountered an
1003 ambiguous control sequence while line-editing. The value must
1004 be specified in milliseconds. If you do not define this
1005 variable, the default value of 100 milliseconds is assumed.
1006 YASH_PS1, YASH_PS1R, YASH_PS1S, YASH_PS2, YASH_PS2R, YASH_PS2S,
1008 YASH_PS4, YASH_PS4S
1009 When not in the POSIXly-correct mode, if any of these variables
1010 is defined, it takes precedence over the corresponding variable
1011 without the YASH_ prefix in the name (e.g. PS1). These
1012 variables are ignored in the POSIXly-correct mode. You should
1013 define them to include yash-specific notations in the prompt,
1014 so that unhandled notations do not mangle the prompt in the
1015 POSIXly-correct mode.
1016 YASH_VERSION
1018 The value is initialized to the version number of the shell
1019 when the shell is started.
1020 Arrays
1022 An array is a variable that contains zero or more strings. The
1023 string values of an array are identified by natural numbers (like
1024 positional parameters).
1025 You can assign values to an array by using a simple command as well
1027 as the array built-in. You can use the unset built-in to remove
1028 arrays.
1029 Arrays cannot be exported as arrays. When an array is exported, it
1031 is treated as a normal variable whose value is a concatenation of
1032 all the array values, each separated by a colon.
1033 Arrays are not supported in the POSIXly-correct mode.
1035
1037 Word expansion is substitution of part of a word with another
1038 particular string. There are seven types of word expansions:
1039 1. Tilde expansion
1041 2. Parameter expansion
1043 3. Command substitution
1045 4. Arithmetic expansion
1047 5. Brace expansion
1049 6. Field splitting
1051 7. Pathname expansion (globbing)
1053 These types of expansions are performed in the order specified above.
1055 Tilde expansion, parameter expansion, command substitution, and
1057 arithmetic expansion are called the four expansions.
1058 Tilde expansion
1060 In tilde expansion, parts of words that start with a tilde (~) are
1061 substituted with particular pathnames. The part of each word that gets
1062 substituted is from the beginning of the word, which is a tilde, up to
1063 (but not including) the first slash (/) in the word. If the word does
1064 not contain a slash, the whole word is substituted. If any character in
1065 the substituted part is quoted, tilde expansion is not performed on the
1066 word.
1067 The results of expansion are determined by the format of the
1069 substituted part:
1070 ~
1072 A single tilde is substituted with the value of the HOME variable.
1073 ~username
1075 A tilde followed by a user name is substituted with the pathname of
1076 the user’s home directory.
1077 ~+
1079 ~+ is substituted with the value of the PWD variable.
1080 ~-
1082 ~- is substituted with the value of the OLDPWD variable.
1083 ~+n, ~-n
1085 where n is a non-negative integer. This type of tilde expansion
1086 yields the pathname of a directory of which ~+n or ~-n is the index
1087 in the directory stack.
1088 When tilde expansion is performed on the value of a variable assignment
1090 that occurs during execution of a simple command, the value is
1091 considered as a colon-separated list of words and those words are each
1092 subject to tilde expansion. For example, the variable assignment
1093 VAR=~/a:~/b:~/c
1095 is equivalent to
1097 VAR=/home/foo/a:/home/foo/b:/home/foo/c
1099 if the value of HOME variable is /home/foo.
1101 The POSIX standard does not prescribe how the shell should behave when
1103 it encounters an error during tilde expansion (e.g., when the HOME
1104 variable is not defined). Yash silently ignores any errors during tilde
1105 expansion; the part of the word that would be substituted is left
1106 intact.
1107 In the POSIXly-correct mode, tilde expansion supports the formats of ~
1109 and ~username only.
1110 Parameter expansion
1112 Parameter expansion expands to the value of a parameter.
1113 The syntax of typical, simple parameter expansion is ${parameter},
1115 which expands to the value of the parameter whose name is parameter.
1116 You can omit the braces (e.g., $parameter) if
1117 · parameter is a special parameter,
1119 · parameter is a positional parameter whose index is a one-digit
1121 integer, or
1122 · parameter is a variable and the parameter expansion is not followed
1124 by a character that can be used as part of a variable name. For
1125 example, ${path}-name is equivalent to $path-name, but ${path}name
1126 and $pathname are different.
1127 If parameter is none of a special parameter, positional parameter, and
1129 variable, it is a syntax error. (Some shells other than yash may treat
1130 such a case as an expansion error.)
1131 If the unset option is disabled and the parameter is an undefined
1133 variable, it is an expansion error. If the unset option is enabled, an
1134 undefined variable expands to the empty string.
1135 More complex syntax of parameter expansion allows modifying the value
1137 of a parameter.
1138 Parameter expansion
1140 ${ prefix parameter index modifier }
1141 The spaces in the syntax definition above are for readability only and
1143 must be omitted. You can omit prefix, index, and/or modifier.
1144 Prefix
1146 The prefix, if any, must be a hash sign (#). If a parameter
1147 expansion has the prefix, the result of expansion is the number of
1148 characters in the value this expansion would be expanded to without
1149 the prefix.
1150 Parameter name
1152 The parameter name (parameter) must be either
1153 · a name of a special parameter, positional parameter, or
1155 variable; or
1156 · another parameter expansion, command substitution, or
1158 arithmetic expansion.
1159 The parameter expansion is expanded to the value of the parameter.
1161 If parameter is an array variable, the values of the array are
1162 field-split like the @ special parameter unless the index [*] is
1163 specified.
1164 If parameter is another expansion, it is called a nested expansion.
1166 Nested expansion cannot be used in the POSIXly-correct mode. The
1167 braces ({ }) of a nested parameter expansion cannot be omitted.
1168 Index.sp An index allows extracting part of the parameter value (or
1169 some of array values).
1170 Index
1172 [word1]
1173 [word1,word2]
1175 where word1 and word2 are parsed in the same manner as normal tokens
1177 except that they are always delimited by , or ] and can contain
1178 whitespace characters.
1179 If there is an index in a parameter expansion, it is interpreted as
1181 follows:
1182 1. Words word1 and word2 are subjected to parameter expansion, command
1184 substitution, and arithmetic expansion.
1185 2. If there is no word2 and if word1 expands to one of *, @, and #,
1187 then that is the interpretation of index and the next step is not
1188 taken.
1189 3. The results of the previous steps (the expanded word1 and word2)
1191 are interpreted and evaluated as an arithmetic expression in the
1192 same manner as in arithmetic expansion. The resulting integers are
1193 the interpretation of index. If the results are not integers, it is
1194 an expansion error. If there is no word2, it is assumed that word2
1195 is equal to word1.
1196 If parameter is an array variable, the index specifies the part of the
1198 array. If parameter is either the * or @ special parameter, the index
1199 specifies the index range of positional parameters. In other cases, the
1200 index specifies the index range of a substring of the parameter value
1201 that is being expanded. In all cases, the specified range of the array
1202 values, positional parameters, or parameter value remains in the
1203 results of the expansion and other values are dropped.
1204 If the interpretation of index is one or two integers, the following
1206 rules apply:
1207 · If the interpreted index value is negative, it wraps around. For
1209 example, the index value of -1 corresponds to the last
1210 value/character.
1211 · It is not an error when the index value is out of range. Existing
1213 values/characters within the range are just selected.
1214 · If the interpretation of either word1 or word2 is 0, the range is
1216 assumed empty and the expansion results in nothing.
1217 If the interpretation of index is one of *, @, and #, it is treated as
1219 follows:
1220 *
1222 If parameter is an array, all the array values are field-split or
1223 concatenated in the same manner as the * special parameter. If
1224 parameter is the * or @ special parameter, the positional
1225 parameters are likewise field-split or concatenated. In other
1226 cases, the interpretation of index is treated as if the
1227 interpretation is the two integers 1 and -1.
1228 @
1230 The interpretation of index is treated as if the interpretation is
1231 the two integers 1 and -1.
1232 #
1234 The interpretation of the # index is special in that it does not
1235 simply specify a range. Instead, the expanded values are
1236 substituted with the count.
1237 If parameter is an array, the result of this parameter expansion
1239 will be the number of values in the array being expanded. If
1240 parameter is the * or @ special parameter, the result will be the
1241 number of current positional parameters. Otherwise, the result will
1242 be the number of characters in the value that is being expanded.
1243 If a parameter expansion does not contain an index, it is assumed to be
1245 [@]. In the POSIXly-correct mode, index cannot be specified.
1246 Example 1. Expansion of a normal variable
1248 The following commands will print the string ABC:
1250 var='123ABC789'
1252 echo "${var[4,6]}"
1253 Example 2. Expansion of positional parameters
1255 The following commands will print the string 2 3 4:
1257 set 1 2 3 4 5
1259 echo "${*[2,-2]}"
1260 Example 3. Expansion of an array
1262 The following commands will print the string 2 3 4:
1264 array=(1 2 3 4 5)
1266 echo "${array[2,-2]}"
1267 Modifier
1269 You can modify the value to be expanded by using modifiers:
1270 -word
1272 If the parameter name (parameter) is an undefined variable, the
1273 parameter expansion is expanded to word. It is not treated as
1274 an error if the unset option is disabled.
1275 +word
1277 If the parameter name (parameter) is an existing variable, the
1278 parameter expansion is expanded to word. It is not treated as
1279 an error if the unset option is disabled.
1280 =word
1282 If the parameter name (parameter) is an undefined variable,
1283 word is assigned to the variable and the parameter expansion is
1284 expanded to word. It is not treated as an error if the unset
1285 option is disabled.
1286 ?word
1288 If the parameter name (parameter) is an undefined variable,
1289 word is printed as an error message to the standard error. If
1290 word is empty, the default error message is printed instead.
1291 :-word, :+word, :=word, :?word
1293 These are similar to the four types of modifiers above. The
1294 only difference is that, if parameter exists and has an empty
1295 value, it is also treated as an undefined variable.
1296 #word
1298 The shell performs pattern matching against the value that is
1299 being expanded, using word as a pattern. If word matches the
1300 beginning of the value, the matching part is removed from the
1301 value and the other part remains as expansion results. The
1302 shortest matching is used if more than one matching is
1303 possible.
1304 ##word
1306 This is similar to #word above. The only difference is that the
1307 longest matching is used if more than one matching is possible.
1308 %word
1310 This is similar to #word above. The only difference is that
1311 matching is tried at the end of the value rather than at the
1312 beginning: if word matches the end of the value, the matching
1313 part is removed from the value and the other part remains as
1314 expansion results.
1315 %%word
1317 This is similar to %word above. The only difference is that the
1318 longest matching is used if more than one matching is possible.
1319 /word1/word2
1321 The shell performs pattern matching against the value that is
1322 being expanded, using word1 as a pattern. If word1 matches any
1323 part of the value, the matching part is replaced with word2 and
1324 the whole value after the replacement remains as expansion
1325 results. If word1 matches more than one part of the value, only
1326 the first part is replaced. The shortest matching is replaced
1327 if more than one matching is possible for the same starting
1328 point in the value.
1329 This modifier cannot be used in the POSIXly-correct mode.
1331 /#word1/word2
1333 This is similar to /word1/word2 above. The only difference is
1334 that word1 matches only at the beginning of the value being
1335 expanded.
1336 /%word1/word2
1338 This is similar to /word1/word2 above. The only difference is
1339 that word1 matches only at the end of the value being expanded.
1340 //word1/word2
1342 This is similar to /word1/word2 above. The only difference is
1343 that all matched parts are replaced if word1 matches more than
1344 one part of the value.
1345 :/word1/word2
1347 This is similar to /word1/word2 above. The only difference is
1348 that the value is replaced only when word1 matches the whole
1349 value.
1350 In all types of modifiers above, words are subjected to the four
1352 expansions when (and only when) they are used.
1353 If parameter is an array variable or the @ or * special parameter,
1355 modifiers affect each value of the array or all positional
1356 parameters.
1357 Command substitution
1359 Command substitution expands to output of commands specified.
1360 Command substitution
1362 $(commands)
1363 `commands`
1365 When command substitution is evaluated, commands are executed by a
1367 subshell with output pipelined to the shell. When the commands
1368 finished, command substitution is substituted with the output of the
1369 commands. Any trailing newline characters in the output are ignored.
1370 When command substitution of the form $(commands) is parsed, the
1372 commands are parsed carefully so that complex commands such as nested
1373 command substitution are parsed correctly. If commands start with (,
1374 you should put a space before commands so that the whole command
1375 substitution is not confused with arithmetic expansion. If the shell is
1376 in the POSIXly-correctly mode, the commands are parsed each time the
1377 command substitution is expanded; otherwise, commands are parsed only
1378 when the command substitution is parsed.
1379 If command substitution is of the form `commands`, the commands are not
1381 parsed when the command substitution is parsed; the commands are parsed
1382 each time the command substitution is expanded. The end of commands is
1383 detected by the first backquote character (`) after the beginning of
1384 commands that is not quoted by a backslash. Backquotes that are part of
1385 commands (typically used for nested command substitution) must be
1386 quoted by backslashes. In commands, backslashes are treated as quotes
1387 only when preceding a dollar ($), backquote, newline, or another
1388 backslash. Additionally, if the command substitution occurs inside
1389 double quotes, double quotes in commands must be quoted with a
1390 backslash. Those backslashes are removed before commands are parsed.
1391 Arithmetic expansion
1393 Arithmetic expansion evaluates an arithmetic expression and expands to
1394 the value of the expression.
1395 Arithmetic expansion
1397 $((expression))
1398 When arithmetic expansion is expanded, the expression is subject to
1400 parameter expansion, command substitution, and (nested) arithmetic
1401 expansion. The expression is parsed in (almost) same manner as an
1402 expression of the C programming language.
1403 Yash allows an expression to be either an integer (of the long type in
1405 C) or a floating-point number (of the double type in C). An operation
1406 on integers yields an integer and an operation involving a
1407 floating-point number yields a floating-point number. In the
1408 POSIXly-correct mode, you can use integers only.
1409 The following operators are available (in the order of precedence):
1411 1. ( )
1413 2. ++ -- (postfix operators)
1415 3. ++ -- + - ~ ! (prefix operators)
1417 4. * / %
1419 5. + - (binary operators)
1421 6. << >>
1423 7. < <= > >=
1425 8. == !=
1427 9. &
1429 10. ^
1431 11. |
1433 12. &&
1435 13. ||
1437 14. ? :
1439 15. = *= /= %= += -= <<= >>= &= ^= |=
1441 The ++ and -- operators cannot be used in the POSIXly-correct mode.
1443 An atomic expression can be one of an integer literal, a floating-point
1445 number literal, and a variable. Literals are parsed in the same manner
1446 as in C. An octal integer literal starts with 0, and hexadecimal with
1447 0x. A floating-point number literal may have an exponent (i.e.
1448 1.23e+6). A variable with a non-numeric value will result in an error
1449 when parsed as a number. An unset variable is treated as a value of
1450 zero.
1451 In the POSIXly-correct mode, variables are always parsed as numbers.
1453 Otherwise, variables are parsed only when they are used as numbers in
1454 computation. Unparsed variables are left intact.
1455 set +o posixly-correct
1457 foo=bar
1458 echo $((0 ? foo : foo)) # prints "bar"
1459 echo $((foo + 0)) # error
1460 Brace expansion
1462 Brace expansion expands to several split words with preceding and
1463 succeeding portions duplicated to each split words. Brace expansion is
1464 expanded only when the brace-expand option is enabled.
1465 Comma-separated brace expansion
1467 {word1,word2,...,wordn}
1468 Range brace expansion
1470 {start..end}
1471 {start..end..delta}
1473 Comma-separated brace expansion is expanded to each comma-separated
1475 word. For example, a{1,2,3}b is expanded to the three words a1b, a2b,
1476 and a3b.
1477 Range brace expansion is expanded to integers in the range defined by
1479 start and end. The difference between each integer can be defined by
1480 delta. If start is larger than end, the results will be in descending
1481 order. When ..delta is omitted, it defaults to 1 or -1. For example,
1482 a{1..3}b is expanded to the three words a1b, a2b, and a3b; and
1483 a{1..7..2}b to the four words a1b, a3b, a5b, and a7b.
1484 Multiple brace expansions can be used in one word. Brace expansions can
1486 also be nested. You can quote braces and/or commas to prevent them from
1487 being treated as brace expansion.
1488 Any errors in brace expansion are silently ignored.
1490 Field splitting
1492 In field splitting, words are split at predefined separators.
1493 Field splitting can occur only within parts of words that resulted from
1495 parameter expansion, command substitution, and arithmetic expansion
1496 that are not between double-quotation marks. Expansion results of the @
1497 special parameter are exceptionally split even between double-quotation
1498 marks.
1499 Separators used in field splitting are defined by the value of the IFS
1501 variable. If the variable does not exist, the value is assumed to be
1502 the three characters of space, tab, and newline.
1503 Characters included in the value of the IFS variable are called IFS
1505 characters. IFS characters that are any of space, tab, and newline are
1506 called IFS whitespace and other IFS characters are called IFS
1507 non-whitespace.
1508 Field splitting is performed as follows:
1510 1. The shell searches words for split points. A split point is one or
1512 more adjacent IFS characters within the word portions where field
1513 splitting can occur. The following steps are taken for each split
1514 point found.
1515 2. If the split point includes one or more IFS non-whitespaces, all
1517 the IFS whitespaces in the split point are ignored and the word is
1518 split at each IFS non-whitespace in the split point.
1519 3. If the split point includes no IFS non-whitespaces, the word is
1521 split at the split point unless it is at the beginning or end of
1522 the word.
1523 4. The split points are removed from the results.
1525 Finally, the last word is removed from the results if:
1527 · the empty-last-field option is not enabled;
1529 · the result is more than one word; and
1531 · the last word is empty.
1533 Note
1535 Words are not split at all when the value of the IFS variable is
1536 empty.
1537 Pathname expansion
1539 Pathname expansion performs pattern matching and expands to pathnames
1540 matched by the pattern.
1541 A word subjected to pathname expansion is treated as a pattern. If one
1543 or more pathnames are found that are matched by the pattern, the
1544 pathnames become the results of the pathname expansion.
1545 Pathname expansion is not performed when the glob option is disabled.
1547 The shell searches readable directories for matching pathnames.
1549 Unreadable directories are silently ignored.
1550 The following options affect the behavior of pathname expansion:
1552 null-glob
1554 This option affects the result of pathname expansion when no
1555 matching pathnames are found. If enabled, the result is no word. If
1556 disabled, the result is the original pattern word.
1557 case-glob
1559 This option specifies case-sensitivity in matching. If enabled,
1560 pattern matching is done case-sensitively.
1561 dot-glob
1563 This option affects matching of filenames that start with a period
1564 (.). If disabled, a period at the beginning of a filename does not
1565 match wildcard patterns (? and *) or bracket expressions. If
1566 enabled, there is no such special treatment of periods.
1567 mark-dirs
1569 If enabled, each resulting pathname that is a directory name is
1570 suffixed by a slash (/).
1571 extended-glob
1573 This option enables the extension. (See below)
1574 Any errors in pathname expansion are silently ignored. If the word is
1576 an invalid pattern, it just becomes the result. The results depend on
1577 the null-glob option when no matching pathnames are found.
1578 Pattern matching is done for each filename (or pathname component) of
1580 pathnames. The shell skips matching for literal patterns that contain
1581 no wildcards or bracket expressions. As a result, the patterns /*/foo
1582 and /*/fo[o] may yield different expansion results when the case-glob
1583 option is disabled; for example, the pattern /*/fo[o] matches the
1584 pathname /bar/FOO but the pattern /*/foo does not because matching is
1585 skipped for foo.
1586 Extension in pathname expansion
1588 The following patterns can be used when the extended-glob option is
1589 enabled.
1590 **
1592 The directory is searched recursively and the pattern matches
1593 any number of directory filenames (each separated by a slash).
1594 Any directory whose name begins with a period is excluded from
1595 search. For example, the pattern dir/**/file can match the
1596 pathnames dir/file, dir/foo/file, dir/a/b/c/file, etc.
1597 This pattern is not effective when appearing at the end of the
1599 whole pattern (i.e. foo/bar/**).
1600 .**
1602 This pattern is like **, but all directories are searched
1603 including ones with a name starting with a period.
1604 ***
1606 This pattern is like **, but if a symbolic link to a directory
1607 is found during recursive search, the directory is searched
1608 recursively as well.
1609 .***
1611 This pattern is like ***, but all directories are searched
1612 including ones with a name starting with a period.
1613
1615 Pattern matching notation is a syntax of patterns that represent
1616 particular sets of strings. When a string is included in the set of
1617 strings a pattern represents, the pattern is said to match the string.
1618 Whether a pattern matches a string or not is defined as follows.
1619 Normal characters
1621 A character that is not quoted or any of special characters defined
1622 below is a normal character, which matches the character itself.
1623 For example, the pattern abc matches the string abc, and not any other
1625 strings.
1626 Single-character wildcard
1628 The character ? matches any single character.
1629 For example, the pattern a?c matches any three-character strings that
1631 starts with a and ends with c, such as aac, abc, and a;c.
1632 Multi-character wildcard
1634 The character * matches any strings (of any length, including the empty
1635 string).
1636 For example, the pattern a*c matches any string that starts with a and
1638 ends with c, such as ac, abc, and a;xyz;c.
1639 Bracket expression
1641 A pattern that is enclosed by brackets ([ and ]) is a bracket
1642 expression. A bracket expression must have at least one character
1643 between the brackets. The characters between the brackets are
1644 interpreted as a bracket expression pattern, which is a below-defined
1645 special notation for bracket expression. A bracket expression pattern
1646 represents a set of characters. The bracket expression matches any one
1647 of the characters in the set the bracket expression pattern represents.
1648 If the opening bracket ([) is followed by an exclamation mark (!), the
1650 exclamation is not treated as part of the bracket expression pattern
1651 and the whole bracket expression instead matches a character that is
1652 not included in the set the bracket expression pattern represents. If
1653 the opening bracket is followed by a caret (^), it is treated like an
1654 exclamation mark as above (but shells other than yash may treat the
1655 caret differently).
1656 If the opening bracket (or the following exclamation or caret, if any)
1658 is followed by a closing bracket (]), it is treated as part of the
1659 bracket expression pattern rather than the end of the bracket
1660 expression. You cannot quote characters in the bracket expression
1661 pattern because quotation is treated before bracket expression.
1662 An opening bracket in a pattern is treated as a normal character if it
1664 is not the beginning of a valid bracket expression.
1665 Normal characters (in bracket expression pattern)
1667 A character that is not any of special characters defined below is a
1668 normal character, which represents the character itself.
1669 For example, the bracket expression pattern abc represents the set of
1671 the three characters a, b, and c. The bracket expression [abc]
1672 therefore matches any of the three characters.
1673 Range expressions
1675 A hyphen preceded and followed by a character (or collating symbol) is
1676 a range expression, which represents the set of the two characters and
1677 all characters between the two in the collation order. A collation
1678 order is an order of characters that is defined in the locale data.
1679 If a hyphen is followed by a closing bracket (]), the bracket is
1681 treated as the end of the bracket expression and the hyphen as a normal
1682 character.
1683 For example, the range expression 3-5 represents the set of the three
1685 characters 3, 4, and 5. The bracket expression [3-5-] therefore matches
1686 one of the four characters 3, 4, 5, and -.
1687 Collating symbols
1689 A collating symbol allows more than one character to be treated as a
1690 single character in matching. A collating symbol is made up of one or
1691 more characters enclosed by the special brackets [. and .].
1692 One or more characters that are treated as a single character in
1694 matching are called a collating element. Precisely, a bracket
1695 expression pattern represents a set of collating elements and a bracket
1696 expression matches a collating element rather than a character, but we
1697 do not differentiate them for brevity here.
1698 For example, the character combination “ch” was treated as a single
1700 character in the traditional Spanish language. If this character
1701 combination is registered as a collating element in the locale data,
1702 the bracket expression [[.ch.]df] matches one of ch, d, and f.
1703 Equivalence classes
1705 An equivalence class represents a set of characters that are considered
1706 equivalent. A equivalence class is made up of a character (or more
1707 precisely, a collating element) enclosed by the special brackets [= and
1708 =].
1709 An equivalence class represents the set of characters that consists of
1711 the character enclosed by the brackets and the characters that are in
1712 the same primary equivalence class as the enclosed character. The shell
1713 consults the locale data for the definition of equivalence classes in
1714 the current locale.
1715 For example, if the six characters a, à, á, â, ã, ä are defined to be
1717 in the same primary equivalence class, the bracket expressions [[=a=]],
1718 [[=à=]], and [[=á=]] match one of the six.
1719 Character classes
1721 A character class represents a predefined set of characters. A
1722 character class is made up of a class name enclosed by the special
1723 brackets [: and :]. The shell consults the locale data for which class
1724 a character belongs to.
1725 The following character classes can be used in all locales:
1727 [:lower:]
1729 set of lowercase letters
1730 [:upper:]
1732 set of uppercase letters
1733 [:alpha:]
1735 set of letters, including the [:lower:] and [:upper:] classes.
1736 [:digit:]
1738 set of decimal digits
1739 [:xdigit:]
1741 set of hexadecimal digits
1742 [:alnum:]
1744 set of letters and digits, including the [:alpha:] and [:digit:]
1745 classes.
1746 [:blank:]
1748 set of blank characters, not including the newline character
1749 [:space:]
1751 set of space characters, including the newline character
1752 [:punct:]
1754 set of punctuations
1755 [:print:]
1757 set of printable characters
1758 [:cntrl:]
1760 set of control characters
1761 For example, the bracket expression [[:lower:][:upper:]] matches a
1763 lower or upper case character. In addition to the classes listed above,
1764 other classes may be used depending on the definition of the current
1765 locale.
1766
1768 Redirection is a feature you can use to modify file descriptors of
1769 commands. By using redirection, you can execute commands with their
1770 standard input/output connected with files or devices other than the
1771 terminal.
1772 You can do redirection by adding redirection operators to a command
1774 (simple command or compound command) In a simple command, redirection
1775 operators may appear anywhere in the command as long as operator tokens
1776 are separated from other tokens. In a compound command, redirection
1777 operators must appear at the end of the command.
1778 Redirection operators are processed before the command body is
1780 executed. More than one redirection operator in a command are processed
1781 in the order of appearance. Redirection operators affect only the
1782 command in which they appear, except when they appear in an exec
1783 built-in without command operands. That is, file descriptors modified
1784 by redirection are restored after the command has finished.
1785 A redirection operator starts with < or >. Redirection operators
1787 starting with < affects the standard input (file descriptor 0) by
1788 default. Redirection operators starting with > affects the standard
1789 output (file descriptor 1) by default. To affect another file
1790 descriptor, you can prefix a redirection operator with a non-negative
1791 integer; the operator will affect the file descriptor specified by the
1792 integer. The integer must immediately precede the < or > without any
1793 whitespaces in between. The integer must not be quoted, either.
1794 Redirection to files
1796 The most common type of redirection is redirection to files.
1797 Redirection of input
1799 < token
1800 Redirection of output
1802 > token
1803 >| token
1805 >> token
1807 Redirection of input and output
1809 <> token
1810 The token is subject to the four expansions. It is also subject to
1812 pathname expansion if the shell is interactive. The expansion result is
1813 treated as the pathname of the file to which redirection is performed.
1814 If the pathname expansion does not result in a single pathname, it is
1815 an error.
1816 In redirection of input, the standard input is replaced with a file
1818 descriptor which is open for read-only access to the target file. If
1819 the target file cannot be opened for read-only access, it is an error.
1820 In redirection of output, the standard output is replaced with a file
1822 descriptor which is open for write-only access to the target file. If
1823 the target file cannot be opened for write-only access, it is an error.
1824 If the target file does not exist, a new empty file is created and
1825 opened. If the target file already exists, the file is opened as
1826 follows:
1827 · For the >| operator, the file is emptied when opened if it is a
1829 regular file.
1830 · For the > operator, the behavior is the same as the >| operator if
1832 the clobber option is enabled. If the option is disabled and the
1833 file is a regular file, it is treated as an error.
1834 · For the >> operator, the file is opened for appending; any output
1836 to the file descriptor is appended to the end of the file.
1837 In redirection of input and output, the standard input is replaced with
1839 a file descriptor which is open for read-and-write access to the target
1840 file. If the file does not exist, a new empty file is created and
1841 opened.
1842 Socket redirection
1844 If the pathname of the target file is of the form
1845 /dev/tcp/host/port or /dev/udp/host/port and the file cannot be
1846 opened in the usual manner, a new socket is opened for
1847 communication with the port of the host. The redirection replaces
1848 the standard input or output with the file descriptor to the
1849 socket.
1850 A stream socket is opened for the form /dev/tcp/host/port and a
1852 datagram socket for the form /dev/udp/host/port. The protocol
1853 actually used for communication is determined by the socket library
1854 the shell uses. Typically, stream sockets use TCP and datagram
1855 sockets UDP.
1856 In socket redirection, the file descriptor is both readable and
1858 writable regardless of the type of the redirection operator used.
1859 Socket redirection is yash’s extension that is not defined in
1861 POSIX. Bash as well has socket redirection as extension.
1862 Duplication of file descriptors
1864 Redirection allows duplicating or closing existing file descriptors.
1865 Duplication of file descriptor
1867 <& token
1868 >& token
1870 The token is subject to expansion as in redirection to files, but it is
1872 treated as a file descriptor rather than a pathname. Thus the expanded
1873 token must be a non-negative integer.
1874 The <& and >& operators duplicate the file descriptor specified by
1876 token to the standard input and output, respectively. (The operators
1877 can be prefixed with a non-negative integer so that the file descriptor
1878 is duplicated to a file descriptor other than the standard input or
1879 output.)
1880 If the expanded token is a single hyphen rather than a non-negative
1882 integer, the file descriptor is closed rather than duplicated. By
1883 default, the <& and >& operators close the standard input and output,
1884 respectively, but the operators can be prefixed with a non-negative
1885 integer so that another file descriptor is closed.
1886 In the POSIXly-correct mode, a file descriptor must be readable when
1888 duplicated by the <& operator and writable when duplicated by the >&
1889 operator.
1890 Here documents and here strings
1892 Here document and here string allow redirection to file descriptors
1893 that reads strings directly specified in shell commands.
1894 Here document
1896 << token
1897 <<- token
1899 Here string
1901 <<< token
1902 In a here document or here string, the standard input is replaced with
1904 a readable file descriptor. When the command reads from the file
1905 descriptor, it will read the contents of the here document/string,
1906 which is defined below.
1907 When a here document operator (<< or <<-) appears in a command, the
1909 shell reads the contents of the here document starting from the next
1910 line. The contents of here documents are not parsed nor executed as
1911 commands. The token after the operand specifies a delimiter that
1912 indicates the end of the contents. (The token is not subject to any
1913 expansion, but quotation is processed.) The contents of the here
1914 document is terminated just before the first line containing the token
1915 only. When using the <<- operator, all tab characters at the beginning
1916 of each line in the here document contents are removed and the
1917 delimiter token may be preceded by tab characters.
1918 If there are more than one here document operator on one line, the
1920 contents of the here documents are parsed in order: The contents of the
1921 first here document starts from the next line and ends before the first
1922 line containing the token that followed the first operator. Just after
1923 that line, the contents of the second here document starts, and so on.
1924 The contents of here documents are treated literally: whitespaces,
1926 tabs, etc. remain as is. The exception is that, when the token is not
1927 quoted at all:
1928 · the contents are subject to parameter expansion, command
1930 substitution, arithmetic expansion.
1931 · a backslash in the contents is treated as quotation if and only if
1933 it precedes $, `, ", or another backslash.
1934 · a backslash followed by a newline is treated as line continuation.
1936 In here string, the token after the operator is subject to expansion as
1938 in redirection to files. The expansion result becomes the contents of
1939 the here string. A newline character is automatically appended to the
1940 end of here string contents.
1941 Here string is yash’s extension that is not defined in POSIX. Other
1943 shells like bash, ksh, and zsh have the same feature.
1944 Pipeline redirection
1946 Pipeline redirection allows opening pipelines that can be used for
1947 arbitrary purposes.
1948 Pipeline redirection
1950 >>| token
1951 The token is subject to expansion as in redirection to files, but it is
1953 treated as a file descriptor rather than a pathname. Thus the expanded
1954 token must be a non-negative integer.
1955 Pipeline redirection opens a new pipeline. The standard output (or the
1957 file descriptor specified before the operator, if any) is replaced with
1958 the file descriptor open for writing to the pipeline. The file
1959 descriptor specified by token is replaced with the file descriptor open
1960 for reading from the pipeline.
1961 Pipeline redirection is yash’s extension that is not defined in POSIX.
1963 Process redirection
1965 Process redirection creates a pipeline connected to another command.
1966 Process redirection
1968 <(command...)
1969 >(command...)
1971 In process redirection, the command specified is executed in a
1973 subshell. If the process redirection is of the form <(command...), the
1974 standard output of command is connected with a pipeline to the standard
1975 input of the command the redirection is associated with. If the process
1976 redirection is of the form >(command...), the standard input of command
1977 is connected with a pipeline to the standard output of the command the
1978 redirection is associated with.
1979 Process redirection is yash’s extension that is not defined in POSIX.
1981 Bash and zsh have a feature called process substitution, which uses the
1982 same syntax as yash’s process redirection, but incompatibly differs in
1983 behavior.
1984
1986 This section describes how commands are executed.
1987 Execution of simple commands
1989 A simple command is executed as follows:
1990 1. All tokens in the simple command are expanded except for assignment
1992 and redirection tokens. If an error occurs during expansion, the
1993 execution of the simple command is aborted with a non-zero exit
1994 status.
1995 In the following steps, the first word of the expansion results is
1997 referred to as command name, and the other words as command
1998 arguments. If there is only one word of the expansion results,
1999 there are no command argument words. If there are none of the
2000 expansion results, there is no command name either.
2001 2. Redirection specified in the command, if any, is processed. The
2003 word token after each redirection operator is expanded. If an error
2004 occurs during processing redirection (including when expanding the
2005 word token), the execution of this simple command is aborted with a
2006 non-zero exit status.
2007 3. Assignments specified in the command, if any, are processed. For
2009 each assignment token, the value is expanded and assigned to the
2010 specified variable. If an error occurs during assignments
2011 (including when expanding the values to be assigned), the execution
2012 of this simple command is aborted with a non-zero exit status.
2013 · If there is no command name or the name denotes a special
2015 built-in, the assignments are permanent: the assigned values
2016 remain after the command has finished (until the variable is
2017 reassigned).
2018 · Otherwise, the assignments are temporary: the assigned values
2020 only last during the execution of this simple command.
2021 The assigned variables are automatically exported when the command
2023 name is specified or the all-export option is enabled.
2024 Note
2026 In other shells, assignments may behave differently: For
2027 special built-ins and functions, assigned variables may not be
2028 exported. For functions, assigned variables may be persistent,
2029 that is, may remain even after the execution of the simple
2030 command.
2031 4. If there is no command name, the command execution ends with the
2033 exit status of zero (unless there are any command substitutions in
2034 the command, in which case the exit status of the simple command is
2035 that of the last executed command substitution).
2036 5. A command to be executed is determined using the command search
2038 algorithm and the command is executed.
2039 · If the command is an external command, the command is executed
2041 by creating a new subshell and calling the “exec” system call
2042 in the subshell. The command name and arguments are passed to
2043 the executed command. Exported variables are passed to the
2044 executed command as environment variables.
2045 · If the command is a built-in, the built-in is executed with the
2047 command arguments passed to the built-in.
2048 · If the command is a function, the contents of the function are
2050 executed with the command arguments as function arguments.
2051 If the command was executed, the exit status of this simple command
2053 is that of the executed command. If the algorithm failed to
2054 determine a command, no command is executed and the exit status is
2055 127. If the shell failed to execute the determined command, the
2056 exit status is 126. If the executed command was killed by a signal,
2057 the exit status is the signal number plus 384.
2058 Note
2060 In shells other than yash, the exit status may be different
2061 when the command was killed by a signal, because the POSIX
2062 standard only requires that the exit status be "greater than
2063 128."
2064 If the shell is not in the POSIXly-correct mode and the algorithm
2065 failed to determine a command, the command eval -i --
2066 "${COMMAND_NOT_FOUND_HANDLER-}" is evaluated. During the command
2067 execution, positional parameters are temporarily set to the command
2068 name and arguments that resulted in the first step. Any local
2069 variables defined during the execution are removed when the
2070 execution is finished. The HANDLED local variable is automatically
2071 defined with the initial value being the empty string. If the
2072 HANDLED variable has a non-empty value when the execution of the
2073 command string is finished, the shell pretends that the command was
2074 successfully determined and executed. The exit status of the simple
2075 command is that of the command string in this case.
2076 Command search
2078 A command that is executed in a simple command is determined by the
2079 command name using the following algorithm:
2080 1. If the command name contains a slash (/), the whole name is
2082 treated as the pathname of an external command. The external
2083 command is determined as the executed command.
2084 2. If the command name is a special built-in, the built-in is
2086 determined as the executed command.
2087 3. If the command name is the name of an existing function, the
2089 function is determined as the executed command.
2090 4. If the command name is a semi-special built-in, the built-in is
2092 determined as the executed command.
2093 5. If the command name is a regular built-in, the built-in is
2095 determined as the executed command unless the shell is in the
2096 POSIXly-correct mode.
2097 6. The shell searches the PATH for a executed command:
2099 The value of the PATH variable is separated by colons. Each
2101 separated part is considered as a directory pathname (an empty
2102 pathname denotes the current working directory). The shell
2103 searches the directories (in the order of appearance) and
2104 checks if any directory directly contains an executable regular
2105 file whose name is equal to the command name. If such a file is
2106 found:
2107 · If the command name is the name of a built-in, the built-in
2109 is determined as the executed command.
2110 · Otherwise, the file is determined as the executed command.
2112 (The file will be executed as an external command.)
2113 If no such file is found, no command is determined as the
2115 executed command.
2116 When the shell finds a file that matches the command name during
2118 the search above, the shell remembers the pathname of the file if
2119 it is an absolute path. When the algorithm above is used for the
2120 same command name again, the shell skips searching and directly
2121 determines the command to be executed. If an executable regular
2122 file no longer exists at the remembered pathname, however, the
2123 shell searches again to update the remembered pathname. You can
2124 manage remembered pathnames using the hash built-in.
2125 Termination of the shell
2127 The shell exits when it reached the end of input and has parsed and
2128 executed all input commands or when the exit built-in is executed. The
2129 exit status of the shell is that of the last command the shell executed
2130 (or zero if no commands were executed). The exit status of the shell is
2131 always between 0 and 255 (inclusive). If the exit status of the last
2132 command is 256 or larger, the exit status of the shell will be the
2133 remainder of the exit status divided by 256.
2134 If an exit handler has been registered by the trap built-in, the
2136 handler is executed just before the shell exits. The exit status of the
2137 commands executed in the handler does not affect the exit status of the
2138 shell.
2139 If a non-interactive shell encountered one of the following errors, the
2141 shell immediately exits with a non-zero exit status:
2142 · A command cannot be parsed due to an syntax error (except during
2144 shell initialization).
2145 · An error occurs during execution of a special built-in in the
2147 POSIXly-correct mode.
2148 · A redirection error occurs in a simple command whose command name
2150 is a special built-in and the shell is in the POSIXly-correct mode.
2151 · An assignment error occurs in a simple command.
2153 · An error occurs during expansion (except during shell
2155 initialization).
2156 Note
2158 Some shells other than yash exit when they fail to find a command
2159 to execute in command search.
2160 Functions
2162 Functions allow executing a compound command as a simple command. A
2163 function can be defined by the function definition command and executed
2164 by a simple command. You can use the unset built-in to remove function
2165 definitions.
2166 There are no functions predefined when yash is started.
2168 A function is executed by executing its body, which is a compound
2170 command. While the function is being executed, positional parameters
2171 are set to the arguments given to the function. The old positional
2172 parameters are restored when the function execution finishes.
2173 Local variables
2175 Local variables are temporary variables that are defined in a
2176 function and exist during the function execution only. They can be
2177 defined by the typeset built-in. They are removed when the function
2178 execution finishes.
2179 Local variables may hide variables that have already been defined
2181 before the function execution had started. An existing variable
2182 becomes inaccessible if a local variable of the same name is
2183 defined in a function. The old variable becomes accessible again
2184 when the function execution finishes.
2185 You cannot create a local variable when not executing a function. A
2187 normal variable is created if you try to do so.
2188 Command execution environment
2190 The shell holds following properties during execution.
2191 · The working directory
2193 · Open file descriptors
2195 · The file creation mask (umask)
2197 · The set of signals whose handler is set to “ignore” (trap)
2199 · Environment variables
2201 · Resource limits (ulimit)
2203 Those properties are inherited from the invoker of the shell to the
2205 shell, and from the shell to each external command executed by the
2206 shell.
2207 The properties can be changed during the execution of the shell by
2209 built-in commands, variable assignments, etc.
2210 Subshells
2212 A subshell is a copy of the shell process. Subshells are used in
2213 execution of groupings, pipelines, etc.
2214 Subshells inherit functions, aliases, etc. defined in the shell as
2216 well as the properties above since subshells are copies of the
2217 shell process. Notable exceptions are:
2218 · Traps registered by the trap built-in are all reset in
2220 subshells except for ones whose action is set to “ignore”. (See
2221 below)
2222 · The interactive mode and job control are disabled in subshells.
2224 Jobs are not inherited by subshells.
2225 Subshells are executed independently of the original shell, so
2227 changes of any properties above do not affect those of the original
2228 shell.
2229 Note
2231 If the subshell contains a single trap built-in, some shells
2232 (but not yash) may not reset the traps on entry to the
2233 subshell.
2234
2236 The interactive mode is a mode of the shell intended for direct
2237 interaction with a user. If yash is in the interactive mode, it is
2238 called an interactive shell.
2239 Whether a shell runs in the interactive mode or not is determined in
2241 the invocation of the shell. After the shell has started up, the
2242 interactive mode cannot be switched on or off.
2243 When the shell is interactive:
2245 · Initialization scripts are executed during invocation.
2247 · The shell checks for mail and prints a command prompt when it reads
2249 a command. Job status changes are also reported if job control is
2250 active. Line-editing may be used depending on the capability of
2251 the terminal.
2252 · Commands executed are automatically registered in command history.
2254 · If a command executed by the shell is killed by a signal other than
2256 SIGINT and SIGPIPE, the shell reports the fact to the standard
2257 error.
2258 · The filename token is subject to pathname expansion in file
2260 redirection.
2261 · The shell does not exit when it encounters a syntax or expansion
2263 error during command execution. (cf. Termination of the shell)
2264 · The shell does not exit when it receives the SIGINT, SIGTERM, or
2266 SIGQUIT signal.
2267 · A signal handler can be changed by the trap built-in even if the
2269 handler had been set to “ignore” when the shell was invoked.
2270 · The value of the - special parameter contains i.
2272 · The shell’s locale reflects the value of the LC_CTYPE variable
2274 whenever the value is changed (if the shell is not in the
2275 POSIXly-correct mode).
2276 · Commands are executed even when the exec option is off.
2278 · The ignore-eof option takes effect when enabled.
2280 · When the shell reaches the end of input or the exit built-in is
2282 executed, the shell checks if there is any stopped job. If so, the
2283 shell prints a warning and does not actually exit.
2284 · The suspend built-in by default cannot stop the shell if it is a
2286 session leader.
2287 · The shell does not exit when the dot built-in fails to find a
2289 script file to read.
2290 · The shell does not exit when the exec built-in fails to execute a
2292 command (if not in the POSIXly-correct mode).
2293 · When a job finished for which the wait built-in has been waiting,
2295 the fact is reported (only if job control is active and not in the
2296 POSIXly-correct mode).
2297 · A prompt is printed when the read built-in reads a second or
2299 following line.
2300 Prompts
2302 The interactive shell prints a prompt just before it reads a command.
2303 The contents of the prompt is specified by the value of the PS1 and PS2
2304 variables. The former is used for reading the first line of the command
2305 and the latter for other lines.
2306 When the prompt is printed, the variable value is subjected to
2308 parameter expansion, command substitution, and arithmetic expansion
2309 (but note that the POSIX standard requires parameter expansion only).
2310 The result of the expansion is parsed by the rules below to make the
2311 actual prompt string, which is printed to the standard error.
2312 In the POSIXly-correct mode, each exclamation mark (!) in the string is
2314 substituted with the command history number of the command that is
2315 being input. Two adjacent exclamation marks (!!) are printed as a
2316 single exclamation. Other characters are printed intact.
2317 If the shell is not in the POSIXly-command mode, the following
2319 notations can be used to format the prompt string. Notations are
2320 replaced with the strings designated in the list below. Characters that
2321 are not interpreted as notations are printed intact.
2322 \a
2324 Bell character (ASCII code: 7)
2325 \e
2327 Escape character (ASCII code: 27)
2328 \j
2330 The number of jobs in the shell.
2331 \n
2333 Newline character (ASCII code: 10)
2334 \r
2336 Carriage return character (ASCII code: 13)
2337 \!
2339 The command history number of the command that is being input
2340 \$
2342 # if the shell’s effective user ID is 0; $ otherwise.
2343 \\
2345 Backslash
2346 \[, \]
2348 These two notations can surround part of the prompt string that is
2349 not visible on the terminal. The surrounded part is ignored when
2350 the shell counts the number of characters that is displayed on the
2351 terminal, thus making characters correctly aligned on the terminal
2352 when the prompt string contains special invisible characters.
2353 \ffontspecs.
2355 When line-editing is active, this notation is replaced with special
2356 characters to change font styles on the terminal if the terminal is
2357 capable of it. If line-editing is inactive or the terminal is
2358 incapable of changing font styles, this notation is silently
2359 ignored. One or more of the following can be used for fontspecs:
2360 k
2362 Change font color to black
2363 r
2365 Change font color to red
2366 g
2368 Change font color to green
2369 y
2371 Change font color to yellow
2372 b
2374 Change font color to blue
2375 m
2377 Change font color to magenta
2378 c
2380 Change font color to cyan
2381 w
2383 Change font color to white
2384 K
2386 Change background color to black
2387 R
2389 Change background color to red
2390 G
2392 Change background color to green
2393 Y
2395 Change background color to yellow
2396 B
2398 Change background color to blue
2399 M
2401 Change background color to magenta
2402 C
2404 Change background color to cyan
2405 W
2407 Change background color to white
2408 t
2410 Make font color or background brighter (can only be used just
2411 after one of the characters above)
2412 d
2414 Change font and background colors to normal
2415 s
2417 Make font standout
2418 u
2420 Make font underlined
2421 v
2423 Make font and background colors reversed
2424 b
2426 Make font blink
2427 i
2429 Make font dim
2430 o
2432 Make font bold
2433 x
2435 Make font invisible
2436 D
2438 Make color and style normal
2439 The actual colors of font and background are defined by the
2441 terminal. Different terminals may use different colors.
2442 In addition to the normal prompt, a prompt string can be displayed to
2444 the right of the cursor if line-editing is active. Those prompts are
2445 called right prompts. The contents of right prompts are defined by the
2446 value of the PS1R and PS2R variables, each corresponding to the PS1 and
2447 PS2 variables.
2448 Using the above-said notations, the font style of command strings the
2450 user inputs can be changed as well as that of prompts. The font style
2451 of command strings is defined by the value of the PS1S and PS2S
2452 variables, each corresponding to the PS1 and PS2 variables. The value
2453 can contain the \ffontspecs. notation only.
2454 When the shell is not in the POSIXly-correct mode, the prompt variables
2456 can be defined with a name prefixed with YASH_ (e.g. YASH_PS1). This
2457 allows using a different prompt string than that in the POSIXly-correct
2458 mode.
2459 When the shell is not in the POSIXly-correct mode, the value of the
2461 PROMPT_COMMAND variable is executed before each prompt.
2462 Command history
2464 Command history is a feature of the shell that remembers executed
2465 commands to allow re-executing them later. Commands executed in the
2466 interactive mode are automatically saved in the command history. Saved
2467 commands can be edited and re-executed using line-editing and the fc
2468 and history built-ins.
2469 Commands are saved line by line. Lines that do not contain any
2471 non-whitespace characters are not saved in the history. Lines that
2472 start with whitespaces are not saved when the hist-space option is on.
2473 Command history is saved in a file. When history is first used after an
2475 interactive shell was started, the shell opens a file to save history
2476 in. The filename is specified by the value of the HISTFILE variable. If
2477 the file contains history data when opened, the data is restored to the
2478 shell’s history. The file contents are updated in real time as the user
2479 inputs commands into the shell. If the HISTFILE variable is not set or
2480 the file cannot be opened successfully, history is not saved in the
2481 file, but the history feature will be functional in all other respects.
2482 The number of commands saved in history is specified by the value of
2484 the HISTSIZE variable. The shell automatically removes old history data
2485 so that the number of saved commands does not exceed the value. If the
2486 HISTSIZE variable is not set or its value is not a natural number, 500
2487 items will be saved in history.
2488 The shell looks at the value of the HISTFILE and HISTSIZE variables
2490 only when the history feature is first used after the shell was
2491 started. “The history feature is used” when:
2492 · the fc or history built-in is executed,
2494 · line-editing is used (regardless of whether or not history data is
2496 recalled in line-editing), or
2497 · a command is input to the shell
2499 Therefore, the variables should be set in initialization scripts.
2501 When more than one instance of yash shares a single history file, all
2503 the shells use the same history data. As a result, commands that have
2504 been executed by a shell instance can be recalled on another shell
2505 instance. Shells sharing the same history should have the same HISTSIZE
2506 value so that they manipulate history data properly.
2507 Yash’s history data file has its own format that is incompatible with
2509 other kinds of shells.
2510 The HISTRMDUP variable can be set to remove duplicate history items.
2512 Mail checking
2514 An interactive shell can notify receipt of email. The shell
2515 periodically checks the modification date/time of a file specified by
2516 the user. If the file has been modified since the previous check, the
2517 shell prints a notification message (except when the shell is not in
2518 the POSIXly-correct mode and the file is empty). By specifying a
2519 mailbox file to be checked, the shell will print a message when the
2520 file has been modified, that is, some mail has been received.
2521 Check is done just before the shell prints a command line prompt. The
2523 interval of checks can be specified by the MAILCHECK variable in
2524 seconds. If the variable value is 0, check is done before every prompt.
2525 If the variable value is not a non-negative integer, no checks are
2526 done.
2527 The file whose modification time is checked is specified by the MAIL
2529 variable. The variable value should be set to the pathname of the file.
2530 If you want to check more than one file or customize the notification
2532 message, you can set the MAILPATH variable instead of the MAIL
2533 variable. When the MAILPATH variable is set, the MAIL variable is
2534 ignored. The value of the MAILPATH variable should be set to one or
2535 more colon-separated pathnames of files to be checked. Each pathname
2536 can be followed by a percent sign (%) and a custom notification
2537 message, which is printed when the corresponding file has been
2538 modified. If the pathname contains a percent sign, it should be quoted
2539 by a backslash. The specified message is subject to parameter
2540 expansion. For example, if the value of the MAILPATH variable is
2541 /foo/mail%New mail!:/bar/mailbox%You've got mail:/baz/mail\%data, the
2542 shell will print
2543 · New mail! when the file /foo/mail has been modified
2545 · You've got mail when the file /bar/mailbox has been modified
2547 · the default message when the file /baz/mail%data has been modified.
2549
2551 Job control is a function of the shell that executes multiple commands
2552 simultaneously and suspends/resumes the commands.
2553 When job control is active:
2555 · Every pipeline executed by the shell becomes a job. A job has its
2557 unique process group ID that is shared among all processes in the
2558 job.
2559 · If the processes of a job are suspended while the shell is waiting
2561 for the processes to finish, the shell continues to the next
2562 command as if the process have finished. The shell remembers the
2563 job as suspended so that it can be resumed later.
2564 · If a job is executed synchronously, the shell sets the foreground
2566 process group of the terminal to the process group of the job. When
2567 the job is finished (or suspended), the shell gets back to the
2568 foreground.
2569 · The subshell executing a command substitution has its own unique
2571 process group ID like a job. However, the shell does not remember
2572 the subshell as a job, so it cannot be suspended or resumed.
2573 · If the shell is interactive, job status is reported before every
2575 command line prompt as if the command jobs -n is executed.
2576 · The standard input of an asynchronous command is not automatically
2578 redirected to /dev/null.
2579 · The shell does not exit when it receives the SIGTSTP signal.
2581 · The value of the - special parameter contains m.
2583 · When a job finished for which the wait built-in has been waiting,
2585 the fact is reported (only if the shell is interactive and not in
2586 the POSIXly-correct mode).
2587 When job control is inactive, processes executed by the shell have the
2589 same process group ID as the shell. The shell treats asynchronous
2590 commands as an uncontrolled job.
2591 You can use the following built-ins to manipulate jobs:
2593 jobs
2595 prints existing jobs
2596 fg and bg
2598 run jobs in the foreground or background
2599 wait
2601 waits for jobs to be finished (or suspended)
2602 disown
2604 forgets jobs
2605 kill
2607 sends a signal to jobs
2608 An interactive job-controlling shell reports jobs status before every
2610 prompt by default. You can set the following options to make the shell
2611 report status at other timings:
2612 notify
2614 the shell reports immediately whenever job status changes.
2615 notify-le
2617 the shell reports immediately when job status changes while
2618 line-editing.
2619 A job is removed from the shell’s job list when:
2621 · it has finished and the jobs built-in reported it,
2623 · the wait built-in successfully waited for the job to finish, or
2625 · the disown built-in removed the job.
2627 Jobs are not removed from the list when an interactive shell
2629 automatically reports the status of jobs.
2630 Note
2632 The word “stop” is synonymous to “suspend” in the context of job
2633 control.
2634 Job ID
2636 Some built-ins use the following notation, which is called job ID, to
2637 specify a job to operate on:
2638 %, %%, %+
2640 the current job
2641 %-
2643 the previous job
2644 %n
2646 the job that has job number n, where n is a positive integer
2647 %string
2649 the job whose name begins with string
2650 %?string
2652 the job whose name contains string
2653 The current job and previous job are jobs selected by the shell
2655 according to the following rules:
2656 · When there is one or more suspended jobs, the current job is
2658 selected from them.
2659 · When there is one or more suspended jobs other than the current
2661 job, the previous job is selected from them.
2662 · The current and previous jobs are always different. When the shell
2664 has only one job, it is the current job and there is no previous
2665 job.
2666 · When the current job finished, the previous job becomes the current
2668 job.
2669 · When the current job is changed, the old current job becomes the
2671 previous job except when the old job finished.
2672 · When the foreground job is suspended, the job becomes the current
2674 job.
2675 Yash has some options to modify the rules of the current/previous job
2677 selection. (The rules above have priority over the options below.)
2678 cur-async
2680 When a new asynchronous command is started, it becomes the current
2681 job.
2682 cur-bg
2684 When a job is resumed by the bg built-in, the job becomes the
2685 current job.
2686 cur-stop
2688 When a job is suspended, it becomes the current job.
2689 The current and previous jobs are not changed as long as the rules
2691 above are met.
2692 The rules of the current/previous job selection defined in the POSIX
2694 standard are looser than yash’s rules above. Other POSIX-compliant
2695 shells may select the current and previous jobs differently.
2696
2698 Built-in commands are commands that are implemented in the shell and
2699 are executed by the shell without external programs.
2700 Types of built-in commands
2702 There are three types of built-in commands in yash: special built-in
2703 commands, semi-special built-in commands and regular built-in commands.
2704 Special built-in commands are much more important commands than others.
2706 They are executed regardless of whether the corresponding external
2707 commands exist or not. Results of variable assignments that occur in a
2708 simple command that invokes a special built-in last after the command
2709 has finished. Moreover, in the POSIXly-correct mode, a non-interactive
2710 shell immediately exits with a non-zero exit status when a redirect
2711 error, assignment error, or misuse of option or operand occurs in a
2712 special built-in command.
2713 Semi special built-in commands are the second important built-in
2715 commands. They are executed regardless of whether the corresponding
2716 external commands exist or not. In other parts they are the same as
2717 regular built-in commands.
2718 Regular built-in commands are less important built-in commands
2720 including commands that can be implemented as external commands or are
2721 not listed in POSIX. In the POSIXly-correct mode, a regular built-in is
2722 executed only when a corresponding external command is found in PATH.
2723 Syntax of command arguments
2725 In this section we explain common rules about command arguments. The
2726 built-in commands of yash follow the rules unless otherwise stated.
2727 There are two types of command arguments. One is options and the other
2729 is operands. An option is an argument that starts with a hyphen (-) and
2730 changes the way the command behaves. Some options take arguments. An
2731 operand is an argument that is not an option and specifies objects the
2732 command operates on.
2733 If you specify more than one option to a command, the order of the
2735 options are normally not significant. The order of operands, however,
2736 affects the command behavior.
2737 An option is either a single-character option or a long option. A
2739 single-character option is identified by one alphabetic character. A
2740 long option is identified by multiple alphabetic characters. The POSIX
2741 standard only prescribes single-character options, so in the
2742 POSIXly-correct mode you cannot use long options.
2743 A single-character option is composed of a hyphen followed by a letter.
2745 For example, -a is a single-character option. A single-character option
2746 that takes an argument requires the argument to be just after the
2747 option name.
2748 Example 4. The set built-in and single-character options
2750 For the set built-in, -m is a single-character option that does not
2752 take an argument and -o is one that takes an argument.
2753 · set -o errexit -m
2755 · set -oerrexit -m
2757 In these two command lines, errexit is the argument to the -o option.
2759 In the second example above, the -o option and its argument are
2761 combined into a single command line argument. The POSIX standard
2762 deprecates that style and any POSIX-conforming applications must
2763 specify options and their arguments as separate command line arguments,
2764 although yash accepts both styles.
2765 You can combine single-character options that do not take arguments
2767 into a single command line argument. For example, the three options -a,
2768 -b and -c can be combined into -abc.
2769 A long option is composed of two hyphens followed by an option name.
2771 For example, --long-option is a long option. You can omit some last
2772 characters of a long option name as long as it is not ambiguous. For
2773 example, you can use --long instead of --long-option if there is no
2774 other options beginning with --long. Like a single-character option, a
2775 long option that takes an argument requires the argument to be a
2776 command line argument just after the option name or to be specified in
2777 the same command line argument as the option name, separated by an
2778 equal sign (=).
2779 Example 5. The fc built-in and long options
2781 For the fc built-in, --quiet is a long option that does not take an
2783 argument and --editor is one that takes an argument.
2784 · fc --editor vi --quiet
2786 · fc --editor=vi --quiet
2788 In these command lines, vi is the argument to the --editor option.
2790 Arguments that are not options (nor arguments to them) are interpreted
2792 as operands. The POSIX standard requires all options should be
2793 specified before any operands. Therefore, in the POSIXly-correct mode,
2794 any arguments that come after the first operand are interpreted as
2795 operands (even if they look like options). If not in the
2796 POSIXly-correct mode, you can specify options after operand.
2797 Regardless of whether the shell is in the POSIXly-correct mode or not,
2799 an argument that is just composed of two hyphens (--) can be used as a
2800 separator between options and operands. All command line arguments
2801 after the -- separator are interpreted as operands, so you can specify
2802 operands that start with a hyphen correctly using the separator.
2803 Example 6. Options and operands to the set built-in
2805 · set -a -b -- -c -d
2807 In this example, -a and -b are options and -c and -d are operands. The
2809 -- separator itself is neither an option nor an operand.
2810 Regardless of whether the shell is in the POSIXly-correct mode or not,
2812 an argument that is just composed of a single hyphen (-) is interpreted
2813 as an operand.
2814
2816 With the line-editing feature, you can edit the command text when you
2817 input a command to an interactive shell. It not only works as a simple
2818 visual-interface editor, but also is integrated with the command
2819 history. You can recall, edit, and execute commands in the history with
2820 line-editing instead of using the fc built-in.
2821 Line-editing has two editing modes, the vi and emacs modes, which each
2823 have their own key binding settings. By switching editing modes, you
2824 can change key bindings used in line-editing. Each mode has a
2825 corresponding shell option, which determines whether the mode is
2826 currently active or not. No more than one mode can be active at a time,
2827 so the options for the other modes are automatically turned off when
2828 you turn on the option for one mode. The whole line-editing feature is
2829 deactivated when those options are off.
2830 When an interactive shell is started, the vi mode is automatically
2832 activated if the standard input and error are both connected to a
2833 terminal.
2834 Line-editing can be used only when the standard input and error are
2836 both connected to a terminal. If not, the shell silently falls back to
2837 the normal input mechanism. While line-editing is being used, the shell
2838 uses the termios interface to change I/O settings of the terminal and
2839 the terminfo interface to parse input key sequences.
2840 Shell options on line-editing
2842 The following options can be set by the set built-in to enable
2843 line-editing and choose an editing mode to activate:
2844 vi
2846 activates the vi mode.
2847 emacs
2849 activates the emacs mode.
2850 The other line-editing-related options are:
2852 le-always-rp
2854 When this options is enabled, the right prompt is always visible:
2855 when the cursor reaches the right prompt, it moves to the next line
2856 from the original position, which would otherwise be overwritten by
2857 input text.
2858 le-comp-debug
2860 When enabled, internal information is printed during completion,
2861 which will help debugging completion scripts.
2862 le-conv-meta
2864 When enabled, the 8th bit of each input byte is always treated as a
2865 meta-key flag, regardless of terminfo data.
2866 le-no-conv-meta
2868 When enabled, the 8th bit of each input byte is never treated as a
2869 meta-key flag, regardless of terminfo data.
2870 The le-conv-meta and le-no-conv-meta options cannot be both enabled
2872 at a time. When either is enabled, the other is automatically
2873 disabled. When neither is enabled, the 8th bit may be treated as a
2874 meta-key flag depending on terminfo data.
2875 le-predict
2877 activates command line prediction.
2878 le-predict-empty
2880 When enabled, and command line prediction is active, suggestions
2881 are also provided for empty input lines.
2882 le-prompt-sp
2884 When enabled, the shell prints a special character sequence before
2885 printing each prompt so that every prompt is printed at the
2886 beginning of a line.
2887 This option is enabled by default.
2889 le-visible-bell
2891 When enabled, the shell flashes the terminal instead of sounding an
2892 alarm when an alert is required.
2893 Editing modes
2895 The vi mode is an editing mode that offers key bindings similar to that
2896 of the vi editor. The vi mode has two sub-modes that are switched
2897 during editing: the insert and command modes. The sub-mode is always
2898 reset to the insert mode when line-editing is started for a new command
2899 line. In the insert mode, most characters are inserted to the buffer as
2900 typed. In the command mode, input characters are treated as commands
2901 that move the cursor, insert/delete text, etc.
2902 The emacs mode offers key bindings similar to the emacs editor. Most
2904 characters are inserted to the buffer as typed, but more characters are
2905 treated as commands than the vi insert mode.
2906 Another sub-mode is used while you enter search keywords. The sub-mode
2908 is called the search mode, which offers slightly different key bindings
2909 depending on the active editing mode.
2910 Line-editing commands
2912 All characters the user enters while line-editing is active are treated
2913 as line-editing commands listed below. The bindkey built-in allows
2914 customizing the key bindings of each mode (except for the search mode).
2915 The list below shows not only the functions of commands but also the
2917 default key bindings. The keywords “vi-insert”, “vi-command”,
2918 “vi-search”, “emacs”, “emacs-search” means the vi insert mode, the vi
2919 command mode, the search mode for the vi mode (the vi search mode), the
2920 emacs mode, and the search mode for the emacs mode (the emacs search
2921 mode), respectively.
2922 Some commands take an argument that affects the function of the
2924 commands. For example, the forward-char command moves the cursor by as
2925 many characters as specified by the argument. To specify an argument,
2926 use the digit-argument command just before another command that takes
2927 an argument.
2928 Basic editing commands
2930 noop
2931 Do nothing.
2932 vi-command
2934 \^[
2935 alert
2937 Alert.
2938 self-insert
2940 Insert the input character at the current cursor position.
2941 Characters escaped by escape sequences cannot be inserted.
2942 vi-insert, emacs
2944 \\
2945 insert-tab
2947 Insert a tab character at the current cursor position.
2948 emacs
2950 \^[\^I
2951 expect-verbatim
2953 Insert a character that is entered just after this command at
2954 the current cursor position. This command can input a character
2955 that cannot be input by the self-insert command, except a null
2956 character ('\0').
2957 vi-insert, vi-search, emacs-search
2959 \^V
2960 emacs
2962 \^Q, \^V
2963 digit-argument
2965 Pass the input digit to the next command as an argument.
2966 This command can be bound to a digit or hyphen. To pass “12” as
2968 an argument to the forward-char command in the vi mode, for
2969 example, enter 12l.
2970 vi-command
2972 1, 2, 3, 4, 5, 6, 7, 8, 9
2973 emacs
2975 \^[0, \^[1, \^[2, \^[3, \^[4, \^[5, \^[6, \^[7, \^[8, \^[9,
2976 \^[-,
2977 bol-or-digit
2979 Like the beginning-of-line command if there is no argument;
2980 like the digit-argument command otherwise.
2981 vi-command
2983 0
2984 accept-line
2986 Finish editing the current line. A newline is automatically
2987 appended to the line. The line will be executed by the shell.
2988 If command line prediction is active, the current prediction
2990 (if any) is ignored. See also the accept-prediction command.
2991 vi-insert, vi-command, emacs, emacs-search
2993 \^J, \^M
2994 abort-line
2996 Abandon the current buffer and finish editing as if an empty
2997 line was input.
2998 vi-insert, vi-command, vi-search, emacs, emacs-search
3000 \!, \^C
3001 eof
3003 Abandon the current buffer and finish editing as if the shell
3004 reached the end of input. This normally makes the shell exit.
3005 eof-if-empty
3007 Like the eof command if the buffer is empty; like the alert
3008 command otherwise.
3009 vi-insert, vi-command
3011 \#, \^D
3012 eof-or-delete
3014 Like the eof command if the buffer is empty; like the
3015 delete-char command otherwise.
3016 emacs
3018 \#, \^D
3019 accept-with-hash
3021 If the current line does not begin with a hash sign (#) or
3022 there is no argument specified for this command, a hash sign is
3023 inserted at the beginning of the line. Otherwise, the beginning
3024 hash sign is removed from the line. Finally, the line is
3025 accepted like the accept-line command.
3026 vi-command
3028 #
3029 emacs
3031 \^[#
3032 accept-prediction
3034 Like the accept-line command, but include the predicted part.
3035 setmode-viinsert
3037 Switch to the vi insert mode.
3038 vi-command
3040 i, \I
3041 setmode-vicommand
3043 Switch to the vi command mode.
3044 vi-insert
3046 \^[
3047 setmode-emacs
3049 Switch to the emacs mode.
3050 expect-char, abort-expect-char
3052 These commands are not meant for use by the user. They are used
3053 by the shell to implement some other commands.
3054 redraw-all
3056 Reprint the prompt and the current line to the terminal.
3057 vi-insert, vi-command, vi-search, emacs, emacs-search
3059 \^L
3060 clear-and-redraw-all
3062 Clear the terminal and reprint the prompt and the current line.
3063 Motion commands
3065 Motion commands move the cursor on the line. Most motion commands
3066 accept an argument. When passed an argument, they repeat the cursor
3067 motion as many times as specified by the argument. Passing “4” as
3068 an argument to the forward-char command, for example, advances the
3069 cursor by four characters.
3070 The shell has several definitions of words as units of distance: A
3072 bigword is one or more adjacent non-whitespace characters. A
3073 semiword is one or more adjacent characters that contain no
3074 whitespaces or punctuations. An emacsword is one or more adjacent
3075 alphanumeric characters. A viword is either:
3076 · one or more adjacent alphanumeric characters and/or underscores
3078 (_), or
3079 · one or more adjacent characters that contain none of
3081 alphanumeric characters, underscores, and whitespaces.
3082 forward-char
3084 Move the cursor to the next character.
3085 vi-insert
3087 \R
3088 vi-command
3090 l, (space), \R
3091 emacs
3093 \R, \^F
3094 backward-char
3096 Move the cursor to the previous character.
3097 vi-insert
3099 \L
3100 vi-command
3102 h, \B, \L, \?, \^H
3103 emacs
3105 \L, \^B
3106 forward-bigword
3108 Move the cursor to the next bigword.
3109 vi-command
3111 W
3112 end-of-bigword
3114 Move the cursor to the next end of a bigword.
3115 vi-command
3117 E
3118 backward-bigword
3120 Move the cursor to the previous bigword.
3121 vi-command
3123 B
3124 forward-semiword
3126 Move the cursor to the next semiword.
3127 end-of-semiword
3129 Move the cursor to the next end of a semiword.
3130 backward-semiword
3132 Move the cursor to the previous semiword.
3133 forward-viword
3135 Move the cursor to the next viword.
3136 vi-command
3138 w
3139 end-of-viword
3141 Move the cursor to the next end of a viword.
3142 vi-command
3144 e
3145 backward-viword
3147 Move the cursor to the previous viword.
3148 vi-command
3150 b
3151 forward-emacsword
3153 Move the cursor to the next emacsword.
3154 emacs
3156 \^[f, \^[F
3157 backward-emacsword
3159 Move the cursor to the previous emacsword.
3160 emacs
3162 \^[b, \^[B
3163 beginning-of-line
3165 Move the cursor to the beginning of the line.
3166 vi-insert, vi-command
3168 \H
3169 emacs
3171 \H, \^A
3172 end-of-line
3174 Move the cursor to the end of the line.
3175 vi-insert
3177 \E
3178 vi-command
3180 $, \E
3181 emacs
3183 \E, \^E
3184 go-to-column
3186 Move the cursor to the nth character on the line, where n is
3187 the argument. Assume n = 1 when no argument.
3188 vi-command
3190 |
3191 first-nonblank
3193 Move the cursor to the first non-blank character on the line.
3194 vi-command
3196 ^
3197 find-char
3199 Move the cursor to the first position where a character that is
3200 entered just after this command appears after the current
3201 cursor position.
3202 vi-command
3204 f
3205 emacs
3207 \^]
3208 find-char-rev
3210 Move the cursor to the last position where a character that is
3211 entered just after this command appears before the current
3212 cursor position.
3213 vi-command
3215 F
3216 emacs
3218 \^[\^]
3219 till-char
3221 Move the cursor to the first position just before a character
3222 that is entered just after this command appears after the
3223 current cursor position.
3224 vi-command
3226 t
3227 till-char-rev
3229 Move the cursor to the last position just after a character
3230 that is entered just after this command appears before the
3231 current cursor position.
3232 vi-command
3234 T
3235 refind-char
3237 Redo the last find-char, find-char-rev, till-char,
3238 till-char-rev command.
3239 vi-command
3241 ;
3242 refind-char-rev
3244 Redo the last find-char, find-char-rev, till-char,
3245 till-char-rev command in the reverse direction.
3246 vi-command
3248 ,
3249 Editing commands
3251 Editing commands modify contents of the buffer. Most editing
3252 commands accept an argument. When passed an argument, they repeat
3253 the modification as many times as specified by the argument.
3254 Texts deleted by commands whose name starts with “kill” are saved
3256 in kill ring, from which deleted contents can be restored to the
3257 buffer. The most recent 32 texts are kept in the kill ring.
3258 delete-char
3260 Delete a character at the current cursor position if no
3261 argument is passed; like the kill-char command otherwise.
3262 vi-insert, emacs
3264 \X
3265 delete-bigword
3267 Delete a bigword at the current cursor position if no argument
3268 is passed; like the kill-bigword command otherwise.
3269 delete-semiword
3271 Delete a semiword at the current cursor position if no argument
3272 is passed; like the kill-semiword command otherwise.
3273 delete-viword
3275 Delete a viword at the current cursor position if no argument
3276 is passed; like the kill-viword command otherwise.
3277 delete-emacsword
3279 Delete a emacsword at the current cursor position if no
3280 argument is passed; like the kill-emacsword command otherwise.
3281 backward-delete-char
3283 Delete a character just before the current cursor position if
3284 no argument is passed; like the backward-kill-char command
3285 otherwise.
3286 vi-insert, emacs
3288 \B, \?, \^H
3289 backward-delete-bigword
3291 Delete a bigword just before the current cursor position if no
3292 argument is passed; like the backward-kill-bigword command
3293 otherwise.
3294 backward-delete-semiword
3296 Delete a semiword just before the current cursor position if no
3297 argument is passed; like the backward-kill-semiword command
3298 otherwise.
3299 vi-insert
3301 \^W
3302 backward-delete-viword
3304 Delete a viword just before the current cursor position if no
3305 argument is passed; like the backward-kill-viword command
3306 otherwise.
3307 backward-delete-emacsword
3309 Delete a emacsword just before the current cursor position if
3310 no argument is passed; like the backward-kill-emacsword command
3311 otherwise.
3312 delete-line
3314 Delete the whole buffer contents.
3315 forward-delete-line
3317 Delete all characters from the current cursor position to the
3318 end of the buffer.
3319 backward-delete-line
3321 Delete all characters before the current cursor position.
3322 vi-insert
3324 \$, \^U
3325 kill-char
3327 Delete a character at the current cursor position and add it to
3328 the kill ring.
3329 vi-command
3331 x, \X
3332 kill-bigword
3334 Delete a bigword at the current cursor position and add it to
3335 the kill ring.
3336 kill-semiword
3338 Delete a semiword at the current cursor position and add it to
3339 the kill ring.
3340 kill-viword
3342 Delete a viword at the current cursor position and add it to
3343 the kill ring.
3344 kill-emacsword
3346 Delete a emacsword at the current cursor position and add it to
3347 the kill ring.
3348 emacs
3350 \^[d, \^[D
3351 backward-kill-char
3353 Delete a character just before the current cursor position and
3354 add it to the kill ring.
3355 vi-command
3357 X
3358 backward-kill-bigword
3360 Delete a bigword just before the current cursor position and
3361 add it to the kill ring.
3362 emacs
3364 \^W
3365 backward-kill-semiword
3367 Delete a semiword just before the current cursor position and
3368 add it to the kill ring.
3369 backward-kill-viword
3371 Delete a viword just before the current cursor position and add
3372 it to the kill ring.
3373 backward-kill-emacsword
3375 Delete a emacsword just before the current cursor position and
3376 add it to the kill ring.
3377 emacs
3379 \^[\B, \^[\?, \^[\^H
3380 kill-line
3382 Delete the whole buffer contents and add it to the kill ring.
3383 forward-kill-line
3385 Delete all characters from the current cursor position to the
3386 end of the buffer and add it to the kill ring.
3387 emacs
3389 \^K
3390 backward-kill-line
3392 Delete all characters before the current cursor position and
3393 add it to the kill ring.
3394 emacs
3396 \$, \^U, \^X\B, \^X\?
3397 put-before
3399 Insert the last-killed text before the current cursor position
3400 and move the cursor to the last character that was inserted.
3401 vi-command
3403 P
3404 put
3406 Insert the last-killed text after the current cursor position
3407 and move the cursor to the last character that was inserted.
3408 vi-command
3410 p
3411 put-left
3413 Insert the last-killed text before the current cursor position
3414 and move the cursor to the last character that was inserted.
3415 emacs
3417 \^Y
3418 put-pop
3420 Replace the just put text with the next older killed text.
3421 This command can be used only just after the put-before, put,
3423 put-left, or put-pop command.
3424 emacs
3426 \^[y, \^[Y
3427 undo
3429 Cancel modification by the last editing command.
3430 vi
3432 u
3433 emacs
3435 \^_, \^X\$, \^X\^U
3436 undo-all
3438 Cancel all modification in the current buffer, restoring the
3439 initial contents.
3440 vi
3442 U
3443 emacs
3445 \^[\^R, \^[r, \^[R
3446 cancel-undo
3448 Cancel cancellation by the last undo or undo-all command.
3449 vi
3451 \^R
3452 cancel-undo-all
3454 Cancel all cancellation by all most recent undo and undo-all
3455 commands.
3456 redo
3458 Repeat modification by the last editing command.
3459 vi-command
3461 .
3462 Completion commands
3464 complete
3465 Complete a word just before the cursor position and, if there
3466 is more than one candidate, show a list of the candidates.
3467 complete-next-candidate
3469 Like the complete command when candidates are not being listed;
3470 otherwise, select the next candidate in the list.
3471 vi-insert, emacs
3473 \^I
3474 complete-prev-candidate
3476 Like the complete command when candidates are not being listed;
3477 otherwise, select the previous candidate in the list.
3478 vi-insert, emacs
3480 \bt
3481 complete-next-column
3483 Like the complete command when candidates are not being listed;
3484 otherwise, select the first candidate in the next column in the
3485 list.
3486 complete-prev-column
3488 Like the complete command when candidates are not being listed;
3489 otherwise, select the first candidate in the previous column in
3490 the list.
3491 complete-next-page
3493 Like the complete command when candidates are not being listed;
3494 otherwise, select the first candidate in the next page in the
3495 list.
3496 complete-prev-page
3498 Like the complete command when candidates are not being listed;
3499 otherwise, select the first candidate in the previous page in
3500 the list.
3501 complete-list
3503 Complete a word just before the cursor position.
3504 If you pass no argument, a list of completion candidates is
3506 shown. Otherwise, the word is completed with the nth candidate
3507 where n is the argument.
3508 emacs
3510 \^[?, \^[=
3511 complete-all
3513 Replace a word just before the cursor position with all
3514 possible completion candidates, each separated by a space.
3515 emacs
3517 \^[*
3518 complete-max
3520 Complete a word just before the cursor position with the
3521 longest prefix of all possible completion candidates.
3522 complete-max-then-list
3524 Works like the complete-max command for the first use, then
3525 like the complete command when used successively.
3526 complete-max-then-next-candidate
3528 Works like the complete-max command for the first use, then
3529 like the complete-next-candidate command when used
3530 successively.
3531 complete-max-then-prev-candidate
3533 Works like the complete-max command for the first use, then
3534 like the complete-prev-candidate command when used
3535 successively.
3536 clear-candidates
3538 Clear the list of completion candidates.
3539 Vi-specific commands
3541 vi-replace-char
3542 Replace the character at the cursor position with a character
3543 that is entered just after this command.
3544 vi-command
3546 r
3547 vi-insert-beginning
3549 Move the cursor to the beginning of the line and switch to the
3550 vi insert mode.
3551 vi-command
3553 I
3554 vi-append
3556 Move the cursor to the next character and switch to the vi
3557 insert mode.
3558 vi-command
3560 I
3561 vi-append-to-eol
3563 Move the cursor to the end of the line and switch to the vi
3564 insert mode.
3565 vi-command
3567 A
3568 vi-replace
3570 Switch to the vi insert mode and start overwriting. While
3571 overwriting, the self-insert command replaces the character at
3572 cursor position rather than inserting a character. Overwriting
3573 ends when the editing mode is changed.
3574 vi-command
3576 R
3577 vi-switch-case
3579 Switch case of characters between the current and next cursor
3580 positions. This command must be followed by a motion command,
3581 which determines the next cursor position.
3582 vi-switch-case-char
3584 Switch case of the character at the current cursor position and
3585 move the cursor to the next character.
3586 vi-command
3588 ~
3589 vi-yank
3591 Add to the kill ring the characters between the current and
3592 next cursor positions. This command must be followed by a
3593 motion command, which determines the next cursor position.
3594 vi-command
3596 y
3597 vi-yank-to-eol
3599 Add to the kill ring the characters from the current cursor
3600 position to the end of the line.
3601 vi-command
3603 Y
3604 vi-delete
3606 Delete characters between the current and next cursor positions
3607 and add it to the kill ring. This command must be followed by a
3608 motion command, which determines the next cursor position.
3609 vi-command
3611 d
3612 vi-delete-to-eol
3614 Delete the characters from the current cursor position to the
3615 end of the line and add it to the kill ring.
3616 vi-command
3618 D
3619 vi-change
3621 Delete characters between the current and next cursor positions
3622 and switch to the vi insert mode. This command must be followed
3623 by a motion command, which determines the next cursor position.
3624 vi-command
3626 c
3627 vi-change-to-eol
3629 Delete the characters from the current cursor position to the
3630 end of the line and switch to the vi insert mode.
3631 vi-command
3633 C
3634 vi-change-line
3636 Delete the whole buffer contents and switch to the vi insert
3637 mode.
3638 vi-command
3640 S
3641 vi-yank-and-change
3643 Like the vi-change command, but the deleted text is added to
3644 the kill ring.
3645 vi-yank-and-change-to-eol
3647 Like the vi-change-to-eol command, but the deleted text is
3648 added to the kill ring.
3649 vi-yank-and-change-line
3651 Like the vi-change-line command, but the deleted text is added
3652 to the kill ring.
3653 vi-substitute
3655 Delete a character at the current cursor position, add it to
3656 the kill ring, and switch to the vi insert mode.
3657 vi-command
3659 s
3660 vi-append-last-bigword
3662 Insert a space and the last bigword in the most recent command
3663 history entry just after the current cursor position and switch
3664 to the vi insert mode. If argument n is passed, the nth bigword
3665 in the entry is inserted instead of the last.
3666 vi-command
3668 _
3669 vi-exec-alias
3671 Execute the value of an alias named _c as editing commands
3672 where c is a character input just after this command.
3673 vi-command
3675 @
3676 vi-edit-and-accept
3678 Start the vi editor to edit the current buffer contents. When
3679 the editor finished, the edited buffer contents is accepted
3680 like the accept-line command unless the exit status of the
3681 editor is non-zero.
3682 vi-command
3684 v
3685 vi-complete-list
3687 Like the complete-list command, but also switch to the vi
3688 insert mode.
3689 vi-command
3691 =
3692 vi-complete-all
3694 Like the complete-all command, but also switch to the vi insert
3695 mode.
3696 vi-command
3698 *
3699 vi-complete-max
3701 Like the complete-max command, but also switch to the vi insert
3702 mode.
3703 vi-command
3705 \\
3706 vi-search-forward
3708 Switch to the vi search mode and start forward history search.
3709 vi-command
3711 ?
3712 vi-search-backward
3714 Switch to the vi search mode and start backward history search.
3715 vi-command
3717 /
3718 Emacs-specific commands
3720 emacs-transpose-chars
3721 Move a character just before the cursor to the right.
3722 emacs
3724 \^T
3725 emacs-transpose-words
3727 Move an emacsword just before the cursor to the right.
3728 emacs
3730 \^[t, \^[T
3731 emacs-downcase-word
3733 Make an emacsword just after the cursor lowercase.
3734 emacs
3736 \^[l, \^[L
3737 emacs-upcase-word
3739 Make an emacsword just after the cursor uppercase.
3740 emacs
3742 \^[u, \^[U
3743 emacs-capitalize-word
3745 Capitalize the first letter of an emacsword just after the
3746 cursor.
3747 emacs
3749 \^[c, \^[u
3750 emacs-delete-horizontal-space
3752 Delete spaces around the cursor. If any argument was passed,
3753 delete spaces just before the cursor only.
3754 emacs
3756 \^[\\
3757 emacs-just-one-space
3759 Delete spaces around the cursor and leave one space. If an
3760 argument is specified, leave as many spaces as the argument.
3761 emacs
3763 \^[ (Escape followed by a space)
3764 emacs-search-forward
3766 Switch to the emacs search mode and start forward history
3767 search.
3768 emacs
3770 \^S
3771 emacs-search-backward
3773 Switch to the emacs search mode and start backward history
3774 search.
3775 emacs
3777 \^R
3778 History-related commands
3780 oldest-history
3781 Recall the oldest entry in the history. If argument n is
3782 passed, the entry whose number is n is recalled instead. The
3783 cursor position remains unchanged.
3784 newest-history
3786 Recall the newest entry in the history. If argument n is
3787 passed, the entry whose number is n is recalled instead. The
3788 cursor position remains unchanged.
3789 return-history
3791 Return to the initial buffer corresponding to none of existing
3792 history entries. If argument n is passed, the entry whose
3793 number is n is recalled instead. The cursor position remains
3794 unchanged.
3795 oldest-history-bol
3797 Recall the oldest entry in the history and move the cursor to
3798 the beginning of the line. If argument n is passed, the entry
3799 whose number is n is recalled instead.
3800 vi-command
3802 G
3803 newest-history-bol
3805 Recall the newest entry in the history and move the cursor to
3806 the beginning of the line. If argument n is passed, the entry
3807 whose number is n is recalled instead.
3808 return-history-bol
3810 Return to the initial buffer corresponding to none of existing
3811 history entries and move the cursor to the beginning of the
3812 line. If argument n is passed, the entry whose number is n is
3813 recalled instead.
3814 vi-command
3816 g
3817 oldest-history-eol
3819 Recall the oldest entry in the history and move the cursor to
3820 the end of the line. If argument n is passed, the entry whose
3821 number is n is recalled instead.
3822 emacs
3824 \^[<
3825 newest-history-eol
3827 Recall the newest entry in the history and move the cursor to
3828 the end of the line. If argument n is passed, the entry whose
3829 number is n is recalled instead.
3830 return-history-eol
3832 Return to the initial buffer corresponding to none of existing
3833 history entries and move the cursor to the end of the line. If
3834 argument n is passed, the entry whose number is n is recalled
3835 instead.
3836 emacs
3838 \^[>
3839 next-history
3841 Recall the next history entry. The cursor position remains
3842 unchanged.
3843 prev-history
3845 Recall the previous history entry. The cursor position remains
3846 unchanged.
3847 next-history-bol
3849 Recall the next history entry and move the cursor to the
3850 beginning of the line.
3851 vi-command
3853 j, +, \D, \^N
3854 prev-history-bol
3856 Recall the previous history entry and move the cursor to the
3857 beginning of the line.
3858 vi-command
3860 k, -, \U, \^P
3861 next-history-eol
3863 Recall the next history entry and move the cursor to the end of
3864 the line.
3865 vi-insert, emacs
3867 \D, \^N
3868 prev-history-eol
3870 Recall the previous history entry and move the cursor to the
3871 end of the line.
3872 vi-insert, emacs
3874 \U, \^P
3875 search-again
3877 Repeat the last command history search.
3878 vi-command
3880 n
3881 search-again-rev
3883 Repeat the last command history search in the reverse
3884 direction.
3885 vi-command
3887 N
3888 search-again-forward
3890 Repeat the last command history search in the forward
3891 direction.
3892 search-again-backward
3894 Repeat the last command history search in the backward
3895 direction.
3896 beginning-search-forward
3898 Recall the next history entry that starts with the same text as
3899 the text from the beginning of the line up to the current
3900 cursor position. The cursor position remains unchanged.
3901 beginning-search-backward
3903 Recall the previous history entry that starts with the same
3904 text as the text from the beginning of the line up to the
3905 current cursor position. The cursor position remains unchanged.
3906 Search mode commands
3908 srch-self-insert
3909 Insert the input character at the current cursor position.
3910 Characters escaped by escape sequences cannot be inserted.
3911 vi-search, emacs-search
3913 \\
3914 srch-backward-delete-char
3916 Delete the last character in the search text. If the text is
3917 empty:
3918 · like the srch-abort-search command when in the vi search
3920 mode, or
3921 · like the alert command when in the emacs search mode.
3923 vi-search, emacs-search
3925 \B, \?, \^H
3926 srch-backward-delete-line
3928 Delete the whole search text.
3929 vi-search, emacs-search
3931 \$, \^U
3932 srch-continue-forward
3934 Find the next matching history entry.
3935 emacs-search
3937 \^S
3938 srch-continue-backward
3940 Find the previous matching history entry.
3941 emacs-search
3943 \^R
3944 srch-accept-search
3946 Finish the search mode, accepting the result being shown.
3947 vi-search
3949 \^J, \^M
3950 emacs-search
3952 \^J, \^[
3953 srch-abort-search
3955 Abort search and restore the previous buffer contents.
3956 vi-search
3958 \^[
3959 emacs-search
3961 \^G
3962 Escape sequences
3964 In the bindkey built-in, escape sequences are used to represent special
3965 keys such as function keys and arrow keys. Every escape sequence starts
3966 with a backslash (\) and thus there is also an escape sequence for a
3967 backslash itself.
3968 Below are available escape sequences:
3970 \\
3972 Backslash (\)
3973 \B
3975 Backspace
3976 \D
3978 Down arrow
3979 \E
3981 End
3982 \H
3984 Home
3985 \I
3987 Insert (Insert-char, Enter-insert-mode)
3988 \L
3990 Left arrow
3991 \N
3993 Page-down (Next-page)
3994 \P
3996 Page-up (Previous-page)
3997 \R
3999 Right arrow
4000 \U
4002 Up arrow
4003 \X
4005 Delete
4006 \!
4008 INTR
4009 \#
4011 EOF
4012 \$
4014 KILL
4015 \?
4017 ERASE
4018 \^@
4020 Ctrl + @
4021 \^A, \^B, ..., \^Z
4023 Ctrl + A, Ctrl + B, ..., Ctrl + Z
4024 Note that Ctrl + I, Ctrl + J, and Ctrl + M are tab, newline, and
4026 carriage return, respectively.
4027 \^[
4029 Ctrl + [ (Escape)
4030 \^\
4032 Ctrl + \
4033 \^]
4035 Ctrl + ]
4036 \^^
4038 Ctrl + ^
4039 \^_
4041 Ctrl + _
4042 \^?
4044 Ctrl + ? (Delete)
4045 \F00, \F01, ..., \F63
4047 F0, F1, ..., F63
4048 \a1
4050 Top-left on keypad
4051 \a3
4053 Top-right on keypad
4054 \b2
4056 Center on keypad
4057 \bg
4059 Beginning
4060 \bt
4062 Back-tab
4063 \c1
4065 Bottom-left on keypad
4066 \c3
4068 Bottom-right on keypad
4069 \ca
4071 Clear-all-tabs
4072 \cl
4074 Close
4075 \cn
4077 Cancel
4078 \co
4080 Command
4081 \cp
4083 Copy
4084 \cr
4086 Create
4087 \cs
4089 Clear-screen or erase
4090 \ct
4092 Clear-tab
4093 \dl
4095 Delete-line
4096 \ei
4098 Exit-insert-mode
4099 \el
4101 Clear-to-end-of-line
4102 \es
4104 Clear-to-end-of-screen
4105 \et
4107 Enter (Send)
4108 \ex
4110 Exit
4111 \fd
4113 Find
4114 \hp
4116 Help
4117 \il
4119 Insert-line
4120 \ll
4122 Home-down
4123 \me
4125 Message
4126 \mk
4128 Mark
4129 \ms
4131 Mouse event
4132 \mv
4134 Move
4135 \nx
4137 Next-object
4138 \on
4140 Open
4141 \op
4143 Options
4144 \pr
4146 Print (Copy)
4147 \pv
4149 Previous-object
4150 \rd
4152 Redo
4153 \re
4155 Resume
4156 \rf
4158 Ref (Reference)
4159 \rh
4161 Refresh
4162 \rp
4164 Replace
4165 \rs
4167 Restart
4168 \sf
4170 Scroll-forward (Scroll-down)
4171 \sl
4173 Select
4174 \sr
4176 Scroll-backward (Scroll-up)
4177 \st
4179 Set-tab
4180 \su
4182 Suspend
4183 \sv
4185 Save
4186 \ud
4188 Undo
4189 \SE
4191 Shift + End
4192 \SH
4194 Shift + Home
4195 \SI
4197 Shift + Insert
4198 \SL
4200 Shift + Left arrow
4201 \SR
4203 Shift + Right arrow
4204 \SX
4206 Shift + Delete
4207 \Sbg
4209 Shift + Beginning
4210 \Scn
4212 Shift + Cancel
4213 \Sco
4215 Shift + Command
4216 \Scp
4218 Shift + Copy
4219 \Scr
4221 Shift + Create
4222 \Sdl
4224 Shift + Delete-line
4225 \Sel
4227 Shift + End-of-line
4228 \Sex
4230 Shift + Exit
4231 \Sfd
4233 Shift + Find
4234 \Shp
4236 Shift + Help
4237 \Smg
4239 Shift + Message
4240 \Smv
4242 Shift + Move
4243 \Snx
4245 Shift + Next
4246 \Sop
4248 Shift + Options
4249 \Spr
4251 Shift + Print
4252 \Spv
4254 Shift + Previous
4255 \Srd
4257 Shift + Redo
4258 \Sre
4260 Shift + Resume
4261 \Srp
4263 Shift + Replace
4264 \Ssu
4266 Shift + Suspend
4267 \Ssv
4269 Shift + Save
4270 \Sud
4272 Shift + Undo
4273 INTR, EOF, KILL, and ERASE are special characters configured by the
4275 stty command. In a typical configuration, they are sent by typing
4276 Ctrl+C, Ctrl+D, Ctrl+U, and Ctrl+H, respectively, but some
4277 configuration uses Ctrl+? instead of Ctrl+H for ERASE.
4278 Command line completion
4280 By using the complete and complete-next-candidate commands, etc., you
4281 can complete command names, options, and operands. By default, the
4282 complete-next-candidate command is bound with the Tab key in the vi
4283 insert and emacs modes.
4284 Type a few first letters of a command name or pathname and hit the Tab
4286 key, and a list of matching names will be shown. You can choose a
4287 candidate from the list to complete the name by hitting the Tab key
4288 again. If there is only one matching name, no list will be shown and
4289 the name will directly be completed.
4290 If the name to be completed contains characters like * and ?, it is
4292 treated as a pattern. The name on the command line will be directly
4293 substituted with all possible names matching the pattern (you cannot
4294 choose from a list).
4295 Normally, command names are completed with command names and command
4297 arguments with pathnames. However, completion functions can be defined
4298 to refine completion results.
4299 Completion details
4301 When doing completion for the first time after the shell has been
4302 started, the INIT file is loaded as if the command string . -AL
4303 completion/INIT is executed. If the file is not found, it is
4304 silently ignored. This automatic loading is mainly intended for
4305 loading completion functions bundled with the shell, but you can
4306 let the shell load your own functions by putting a file in the load
4307 path.
4308 When completing a command name, the shell executes the
4310 completion//command function and when completing a command
4311 argument, the completion//argument function. If those completion
4312 functions are not defined, the shell just completes with command
4313 names or pathnames. When completing other names, such as the user
4314 name in tilde expansion and the parameter name in parameter
4315 expansion, completion functions are never used: the shell just
4316 completes with user names, parameter names, or whatever applicable.
4317 Completion functions are executed without any arguments. The
4319 following local variables are automatically defined while executing
4320 completion functions:
4321 IFS
4323 The value is the three characters of a space, a tab, and a
4324 newline, which are the default value of the variable.
4325 WORDS
4327 This variable is an array whose elements are a command name and
4328 arguments that have already been entered before the argument
4329 being completed. When completing a command name, the array has
4330 no elements.
4331 TARGETWORD
4333 The value is the partially entered command name or argument
4334 that is being completed.
4335 Completion candidates are generated by executing the complete
4337 built-in during a completion function.
4338 Completion functions must not perform I/O to the terminal, or
4340 displayed text will be corrupted. Completion functions should run
4341 as quickly as possible for better user experience.
4342 While a completion function is being executed:
4344 · the POSIXly-correct mode and the err-return option are
4346 temporarily disabled,
4347 · the err-exit option is temporarily ignored, and
4349 · traps are not executed.
4351 Command line prediction
4353 This is an experimental feature. When the le-predict option is enabled,
4354 the shell automatically tries to predict a command string fragment that
4355 follows the part of the command you have already typed in line-editing.
4356 For example, assume you have once typed the command ls Documents. Next
4358 time you start typing ls Doc, the shell will show uments just after the
4359 cursor. If you are satisfied with this suggestion, you can move the
4360 cursor to the right by the forward-char or any other motion commands
4361 instead of typing the rest of the command. After moving the cursor
4362 after the last s, you can use the accept-line command to execute the
4363 command. You can also use the accept-prediction command to immediately
4364 execute the suggested command without moving the cursor.
4365 To distinguish the typed part and the predicted part of a command
4367 string, you can change the font style of the typed part by setting the
4368 PS1S variable. Customizing the font style of the predicted part is not
4369 (yet) supported; it is always shown in the default style.
4370 When you move the cursor to the right, the predicted part up to the
4372 cursor becomes the typed part as if you actually typed it. Moving the
4373 cursor to the left does not turn the typed part back to the prediction.
4374 Use deletion commands such as backward-delete-char to delete typed
4375 command fragment.
4376 The predicted part of the command is shown only when the cursor is at
4378 the end of the typed part.
4379 By default, the predicted part is shown after you start typing a
4381 command string. By enabling the le-predict-empty option, the predicted
4382 part is also shown before you type the first character of the command
4383 string.
4384 The prediction algorithm suggests command fragments on the basis of the
4386 command history. The algorithm considers recent history entries more
4387 probable. It also takes command succession patterns into account. A
4388 predicted command fragment is not always a complete valid command
4389 because less probable part of the fragment is excluded from prediction.
4390
4392 Yash behaves as defined in POSIX.1-2008, Shell & Utilities for the most
4393 part, but some functionalities disobey POSIX for usability. When full
4394 POSIX-conformance is needed, you can enable the POSIXly-correct mode to
4395 make yash obey POSIX as much as possible.
4396 If yash is started with the name “sh”, the POSIXly-correct mode is
4398 automatically enabled. The -o posixly-correct command-line option also
4399 enables the POSIXly-correct mode. After yash has been started, the
4400 POSIXly-correct mode can be enabled by executing the command string set
4401 -o posixly-correct.
4402 When the POSIXly-correct mode is on, yash not only tries to obey the
4404 requirements by POSIX, but also treats as errors most conditions where
4405 the behavior is undefined or unspecified by POSIX. As a result, most
4406 yash-specific functionalities are disabled in the POSIXly-correct mode.
4407 Below is the complete list of the behavioral differences between when
4409 yash is in the POSIXly-correct mode and when not. When the
4410 POSIXly-correct mode is enabled:
4411 · Different initialization scripts are used.
4413 · If the shell was started with the -c option, sh -c (instead of yash
4415 -c) is printed as the script pathname on a syntax error.
4416 · Global aliases are not substituted.
4418 · Nested commands in a compound command must not be empty.
4420 · Words expanded in a for loop are assigned as a global variable
4422 rather than a local. The variable must have a portable (ASCII-only)
4423 name.
4424 · The first pattern in a case command cannot be esac.
4426 · The ! keyword cannot be followed by ( without any whitespaces
4428 in-between.
4429 · The double-bracket command cannot be used.
4431 · The function keyword cannot be used for function definition. The
4433 function must have a portable (ASCII-only) name.
4434 · Simple commands cannot assign to arrays.
4436 · Changing the value of the LC_CTYPE variable after the shell has
4438 been initialized does not affect the shell’s locale.
4439 · The RANDOM variable cannot be used to generate random numbers.
4441 · Tilde expansion only expands ~ and ~username.
4443 · Parameter expansion cannot be nested. No indexes or modifiers with
4445 word2 are allowed.
4446 · The commands in a command substitution of the form $(commands) are
4448 parsed every time the substitution is executed.
4449 · In arithmetic expansion, fractional numbers and the ++ and --
4451 operators cannot be used. All variables must be numeric.
4452 · The operand of a redirection cannot be the integer prefix to a next
4454 redirection operator.
4455 · A compound command with a redirection cannot be immediately
4457 followed by a keyword like } and fi.
4458 · In a redirection to a file, if the pathname expansion yielded more
4460 than one or no pathname, it is not immediately treated as an error.
4461 Instead, the shell tries to treat the word before the expansion as
4462 a pathname.
4463 · A file descriptor must be readable and writable when duplicated by
4465 the <& and >& redirection operator, respectively.
4466 · Socket redirection, here strings, pipe redirection, and process
4468 redirection cannot be used.
4469 · When executing a simple command, failure in command search does not
4471 trigger execution of the COMMAND_NOT_FOUND_HANDLER variable.
4472 · In command search, a regular built-in needs to have a corresponding
4474 external command for the built-in to be found.
4475 · Some built-ins behave differently. Especially, long command-line
4477 options (as well as some others) cannot be used.
4478 · A non-interactive shell exits when a special built-in is given a
4480 syntactically wrong arguments or when an error occurs in assignment
4481 or redirection with a special built-in.
4482 · An interactive shell does not execute the PROMPT_COMMAND variable
4484 before printing a prompt. The values of the PS1, PS2, and PS4
4485 variables are parsed differently. Prompt variables with a YASH_
4486 prefix (e.g. YASH_PS1) are not used.
4487 · In mail checking, a notification message is printed if the file has
4489 been modified, regardless of whether the file is empty.
4490
4492 How can I use Unicode (non-ASCII) characters?
4493 You need to set locale environment variables to enable Unicode
4494 character support.
4495 If the variables have already been configured for your preference, you
4497 probably don’t have to do anything. To check the current locale
4498 configurations, you can use the locale command:
4499 $ locale
4501 LANG=
4502 LC_CTYPE="en_US.utf8"
4503 LC_NUMERIC="en_US.utf8"
4504 LC_TIME="en_US.utf8"
4505 LC_COLLATE="en_US.utf8"
4506 LC_MONETARY="en_US.utf8"
4507 LC_MESSAGES="en_US.utf8"
4508 LC_PAPER="en_US.utf8"
4509 LC_NAME="en_US.utf8"
4510 LC_ADDRESS="en_US.utf8"
4511 LC_TELEPHONE="en_US.utf8"
4512 LC_MEASUREMENT="en_US.utf8"
4513 LC_IDENTIFICATION="en_US.utf8"
4514 LC_ALL=en_US.utf8
4515 In this example, the locale command shows that all the locale setting
4517 categories are configured for the English language, the United States
4518 region, and the UTF-8 encoding.
4519 If the current configuration does not seem to match your preference,
4521 set the LC_ALL variable like this:
4522 export LC_ALL=en_US.utf8
4524 If you want to use other languages, regions, or encodings, you have to
4526 set the variable to a different value. Please consult your OS’s
4527 documentation to learn how to configure these variables in detail.
4528 If you want to apply the same configuration every time you start yash,
4530 write the command in ~/.yashrc or ~/.yash_profile.
4531 If yash still rejects Unicode characters being entered, see the section
4533 below regarding line-editing.
4534 Line-editing does not work
4536 First, type echo $TERM and see if it prints a sane value. xterm is the
4537 safest value that should work on any existing environment. Colored
4538 versions like xterm-16color and other terminal types like rxvt and
4539 vt100 may also work. All possible values can be listed by the toe
4540 command. It’s most desirable to choose a value that matches the actual
4541 terminal type you are using, but it might not work if the terminal type
4542 you chose is not supported on the system on which yash is running. If
4543 so, try changing the TERM value by export TERM=xterm, for example, to
4544 find a value that works.
4545 If line-editing works but you have trouble entering Unicode (non-ASCII)
4547 characters, try enabling the le-no-conv-meta option by set -o
4548 le-no-conv-meta.
4549
4551 This chapter defines the syntax of the shell command language.
4552 Note
4554 Some of the syntactic features described below are not supported in
4555 the POSIXly-correct mode.
4556 Tokenization
4558 The characters of the input source code are first delimited into
4559 tokens. Tokens are delimited so that the earlier token spans as long as
4560 possible. A sequence of one or more unquoted blank characters delimits
4561 a token.
4562 The following tokens are the operator tokens:
4564 & && ( ) ; ;; | || < << <& <( <<- <<< <> > >> >& >( >>| >| (newline)
4566 Note
4568 Unlike other programming languages, the newline operator is a token
4569 rather than a white space.
4570 Characters that are not blank nor part of an operator compose a word
4572 token. Words are parsed by the following parsing expression grammar:
4573 Word
4575 (WordElement / !SpecialChar .)+
4576 WordElement
4578 \ . /
4579 ' (!' .)* ' /
4581 " QuoteElement* " /
4583 Parameter /
4585 Arithmetic /
4587 CommandSubstitution
4589 QuoteElement
4591 \ ([$`"\] / <newline>) /
4592 Parameter /
4594 Arithmetic /
4596 CommandSubstitutionQuoted /
4598 ![`"\] .
4600 Parameter
4602 $ [@*#?-$! [:digit:]] /
4603 $ PortableName /
4605 $ ParameterBody
4607 PortableName
4609 ![0-9] [0-9 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_]+
4610 ParameterBody
4612 { ParameterNumber? (ParameterName / ParameterBody / $ ParameterBody
4613 / Arithmetic / CommandSubstitution) ParameterIndex?
4614 ParameterMatch? }
4615 ParameterNumber
4617 # ![}+=:/%] !([-?#] !})
4618 ParameterName
4620 [@*#?-$!] /
4621 [[:alnum:] _]+
4623 ParameterIndex
4625 [ ParameterIndexWord (, ParameterIndexWord)? ]
4626 ParameterIndexWord
4628 (WordElement / !["'],] .)+
4629 ParameterMatch
4631 :? [-+=?] ParameterMatchWord /
4632 (# / ## / % / %%) ParameterMatchWord /
4634 (:/ / / [#%/]?) ParameterMatchWordNoSlash (/ ParameterMatchWord)?
4636 ParameterMatchWord
4638 (WordElement / !["'}] .)*
4639 ParameterMatchWordNoSlash
4641 (WordElement / !["'/}] .)*
4642 Arithmetic
4644 $(( ArithmeticBody* ))
4645 ArithmeticBody
4647 \ . /
4648 Parameter /
4650 Arithmetic /
4652 CommandSubstitution /
4654 ( ArithmeticBody ) /
4656 ![`()] .
4658 CommandSubstitution
4660 $( CompleteProgram ) /
4661 ` CommandSubstitutionBody* `
4663 CommandSubstitutionQuoted
4665 $( CompleteProgram ) /
4666 ` CommandSubstitutionBodyQuoted* `
4668 CommandSubstitutionBody
4670 \ [$`\] /
4671 !` .
4673 CommandSubstitutionBodyQuoted
4675 \ [$`\`] /
4676 !` .
4678 SpecialChar
4680 [|&;<>()`\"' [:blank:]] / <newline>
4681 The set of terminals of the grammar is the set of characters that can
4683 be handled on the environment in which the shell is run (a.k.a.
4684 execution character set), with the exception that the set does not
4685 contain the null character ('\0').
4686 Strictly speaking, the definition above is not a complete parsing
4688 expression grammar because the rule for CommandSubstitution (Quoted)
4689 depends on CompleteProgram which is a non-terminal of the syntax.
4690 Token classification
4692 After a word token is delimited, the token may be further
4693 classified as an IO_NUMBER token, reserved word, name word,
4694 assignment word, or just normal word. Classification other than the
4695 normal word is applied only when applicable in the context in which
4696 the word appears. See Tokens and keywords for the list of the
4697 reserved words (keywords) and the context in which a word may be
4698 recognized as a reserved word.
4699 A token is an IO_NUMBER token iff it is composed of digit
4701 characters only and immediately followed by < or >.
4702 An assignment token is a token that starts with a name followed by
4704 =:
4705 AssignmentWord
4707 AssignmentPrefix Word
4708 AssignmentPrefix
4710 Name =
4711 Name
4713 ![[:digit:]] \[[:alnum:] _]+
4714 Comments
4716 A comment begins with # and continues up to (but not including) the
4717 next newline character. Comments are treated like a blank character
4718 and do not become part of a token. The initial # of a comment must
4719 appear as if it would otherwise be the first character of a word
4720 token; Other #s are just treated as part of a word token.
4721 Comment
4723 # (!<newline> .)*
4724 Syntax
4726 After tokens have been delimited, the sequence of the tokens is parsed
4727 according to the context-free grammar defined below, where *, +, and ?
4728 should be interpreted in the same manner as standard regular
4729 expression:
4730 CompleteProgram
4732 NL* | CompoundList
4733 CompoundList
4735 NL* AndOrList ((; | & | NL) CompleteProgram)?
4736 AndOrList
4738 Pipeline ((&& | ||) NL* Pipeline)*
4739 Pipeline
4741 !? Command (| NL* Command)*
4742 Command
4744 CompoundCommand Redirection* |
4745 FunctionDefinition |
4747 SimpleCommand
4749 CompoundCommand
4751 Subshell |
4752 Grouping |
4754 IfCommand |
4756 ForCommand |
4758 WhileCommand |
4760 CaseCommand |
4762 DoubleBracketCommand |
4764 FunctionCommand
4766 Subshell
4768 ( CompoundList )
4769 Grouping
4771 { CompoundList }
4772 IfCommand
4774 if CompoundList then CompoundList (elif CompoundList then
4775 CompoundList)* (else CompoundList)? fi
4776 ForCommand
4778 for Name ((NL* in Word*)? (; | NL) NL*)? do CompoundList done
4779 WhileCommand
4781 (while | until) CompoundList do CompoundList done
4782 CaseCommand
4784 case Word NL* in NL* CaseList? esac
4785 CaseList
4787 CaseItem (;; NL* CaseList)?
4788 CaseItem
4790 (? Word (| Word)* ) CompleteProgram
4791 DoubleBracketCommand
4793 [[ Ors ]]
4794 Ors
4796 Ands (|| Ands)*
4797 Ands
4799 Nots (&& Nots)*
4800 Nots
4802 !* Primary
4803 Primary
4805 (-b | -c | -d | -e | -f | -G | -g | -h | -k | -L | -N | -n | -O |
4806 -o | -p | -r | -S | -s | -t | -u | -w | -x | -z) Word |
4807 Word (-ef | -eq | -ge | -gt | -le | -lt | -ne | -nt | -ot | -veq |
4809 -vge | -vgt | -vle | -vlt | -vne | = | == | === | =~ | != | !== | <
4810 | >) Word |
4811 ( Ors ) |
4813 Word
4815 FunctionCommand
4817 function Word (( ))? NL* CompoundCommand Redirection*
4818 FunctionDefinition
4820 Name ( ) NL* CompoundCommand Redirection*
4821 SimpleCommand
4823 (Assignment | Redirection) SimpleCommand? |
4824 Word (Word | Redirection)*
4826 Assignment
4828 AssignmentWord |
4829 AssignmentPrefix( NL* (Word NL*)* )
4831 Redirection
4833 IO_NUMBER? RedirectionOperator Word |
4834 IO_NUMBER? <( CompleteProgram ) |
4836 IO_NUMBER? >( CompleteProgram )
4838 RedirectionOperator
4840 < | <> | > | >| | >> | >>| | <& | >& | << | <<- | <<<
4841 NL
4843 <newline>
4844 In the rule for Primary, Word tokens must not be ]]. Additionally, if a
4846 Primary starts with a Word, it must not be any of the possible unary
4847 operators allowed in the rule.
4848 In the rule for SimpleCommand, a Word token is accepted only when the
4850 token cannot be parsed as the first token of an Assignment.
4851 In the rule for Assignment, the ( token must immediately follow the
4853 AssignmentPrefix token, without any blank characters in between.
4854 Here-document contents do not appear as part of the grammar above. They
4856 are parsed just after the newline (NL) token that follows the
4857 corresponding redirection operator.
4858 Alias substitution
4860 Word tokens are subject to alias substitution.
4861 · If a word is going to be parsed as a Word of a SimpleCommand,
4863 the word is subjected to alias substitution of any kind (normal
4864 and global aliases).
4865 · If a word is the next token after the result of an alias
4867 substitution and the substitution string ends with a blank
4868 character, then the word is also subjected to alias
4869 substitution of any kind.
4870 · Other words are subjected to global alias substitution unless
4872 the shell is in the POSIXly-correct mode.
4873 Tokens that are classified as reserved words are not subject to
4875 alias substitution.
4876
4878 The alias built-in defines and/or prints aliases.
4879 Syntax
4881 · alias [-gp] [name[=value]...]
4882 Description
4884 The alias built-in defines and/or prints aliases as specified by
4885 operands. The printed aliases can be used as (part of) shell commands.
4886 The built-in prints all currently defined aliases when given no
4887 operands.
4888 Options
4890 -g, --global
4891 With this option, aliases are defined as global aliases; without
4892 this option, as normal aliases.
4893 -p, --prefix
4895 With this option, aliases are printed in a full command form like
4896 alias -g foo='bar'. Without this option, only command operands are
4897 printed like foo='bar'.
4898 Operands
4900 name
4901 The name of an alias that should be printed.
4902 name=value
4904 The name and value of an alias that is being defined.
4905 Exit status
4907 The exit status of the alias built-in is zero unless there is any
4908 error.
4909 Notes
4911 The characters that cannot be used in an alias name are the space, tab,
4912 newline, and any of =$<>\'"`;&|()#. You can use any characters in an
4913 alias value.
4914 The alias built-in is a semi-special built-in.
4916 The POSIX standard defines no options for the alias built-in, thus no
4918 options are available in the POSIXly correct mode.
4919
4921 The array built-in prints or modifies arrays.
4922 Syntax
4924 · array
4925 · array name [value...]
4927 · array -d name [index...]
4929 · array -i name index [value...]
4931 · array -s name index value
4933 Description
4935 When executed without any option or operands, the built-in prints all
4936 array definitions to the standard output in a form that can be parsed
4937 as commands.
4938 When executed with name and values (but without an option), the
4940 built-in sets the values as the values of the array named name.
4941 With the -d (--delete) option, the built-in removes the indexth values
4943 of the array named name. The number of values in the array will be
4944 decreased by the number of the indexes specified. If the indexth value
4945 does not exist, it is silently ignored.
4946 With the -i (--insert) option, the built-in inserts values into the
4948 array named name. The number of values in the array will be increased
4949 by the number of the values specified. The values are inserted between
4950 the indexth and next values. If index is zero, the values are inserted
4951 before the first value. If index is larger than the number of values in
4952 the array, the values are appended after the last element.
4953 With the -s (--set) option, the built-in sets value as the indexth
4955 value of the array named name. The array must have at least index
4956 values.
4957 Options
4959 -d, --delete
4960 Delete array values.
4961 -i, --insert
4963 Insert array values.
4964 -s, --set
4966 Set an array value.
4967 Operands
4969 name
4970 The name of an array to operate on.
4971 index
4973 The index to an array element. The first element has the index of
4974 1.
4975 value
4977 A string to which the array element is set.
4978 Exit status
4980 The exit status of the array built-in is zero unless there is any
4981 error.
4982 Notes
4984 The array built-in is not defined in the POSIX standard.
4985 The command array name value... is equivalent to the assignment
4987 name=(value...).
4988
4990 The bg built-in resumes a job in the background.
4991 Syntax
4993 · bg [job...]
4994 Description
4996 The bg built-in sends the SIGCONT signal to the specified job. As a
4997 result, the job is resumed in the background (if it has been
4998 suspended).
4999 The name of the job is printed when the job is resumed.
5001 The built-in can be used only when job control is enabled.
5003 Operands
5005 job
5006 The job ID of the job to be resumed.
5007 More than one job can be specified at a time. The current job is
5009 resumed if none is specified.
5010 The percent sign (%) at the beginning of a job ID can be omitted if
5012 the shell is not in the POSIXly-correct mode.
5013 Exit status
5015 The exit status of the bg built-in is zero unless there is any error.
5016 Notes
5018 The bg built-in is a semi-special built-in.
5019 The POSIX standard provides that the built-in shall have no effect when
5021 the job is already running. The bg built-in of yash, however, always
5022 sends the SIGCONT signal to the job.
5023
5025 The bindkey built-in prints or modifies key bindings used in
5026 line-editing.
5027 Syntax
5029 · bindkey -aev [key [command]]
5030 · bindkey -l
5032 Description
5034 When executed with the -l (--list) option, the built-in lists all
5035 available line-editing commands to the standard output.
5036 When executed with one of the other options, the built-in prints or
5038 modifies key bindings for the editing mode specified by the option:
5039 · Without key or command, all currently defined bindings are printed
5041 to the standard output in a form that can be parsed as commands
5042 that restore the current bindings when executed.
5043 · With key but without command, only the binding for the given key is
5045 printed.
5046 · With key and command, key is bound to command.
5048 Options
5050 -a, --vi-command
5051 Print or modify bindings for the vi command mode.
5052 -e, --emacs
5054 Print or modify bindings for the emacs mode.
5055 -v, --vi-insert
5057 Print or modify bindings for the vi insert mode.
5058 Operands
5060 key
5061 A character sequence of one or more keys that is bound to an
5062 editing command. The sequence may include escape sequences.
5063 command
5065 A line-editing command to which key is bound. If command is a
5066 single hyphen (-), key is unbound.
5067 Exit status
5069 The exit status of the bindkey built-in is zero unless there is any
5070 error.
5071 Notes
5073 The bindkey built-in is a semi-special built-in. In the POSIX standard,
5074 it is defined as a command with unspecified behavior.
5075
5077 The break built-in aborts a loop being executed.
5078 Syntax
5080 · break [nest]
5081 · break -i
5083 Description
5085 When executed without the -i (--iteration) option, the built-in aborts
5086 a currently executed for, while, or until loop. When executed in nested
5087 loops, it aborts the nestth innermost loop. The default nest is one. If
5088 the number of currently executed nested loops is less than nest, the
5089 built-in aborts the outermost loop.
5090 When executed with the -i (--iteration) option, the built-in aborts the
5092 currently executed (innermost) iterative execution.
5093 Options
5095 -i, --iteration
5096 Abort an iterative execution instead of a loop.
5097 Operands
5099 nest
5100 The number of loops to abort, which must be a positive integer.
5101 Exit status
5103 The exit status of the break built-in is:
5104 · zero if a loop was successfully aborted.
5106 · that of the command that was executed just before the break
5108 built-in if an iterative execution was successfully aborted.
5109 Notes
5111 The break built-in is a special built-in.
5112 The POSIX standard defines no options for the break built-in; the
5114 built-in accepts no options in the POSIXly-correct mode.
5115 Treatment of currently executed loops that are not lexically enclosing
5117 the break built-in is unspecified in POSIX. Examples of such loops
5118 include:
5119 · A loop invoking a function in which the break built-in is used.
5121 · A loop in which a trap action is executed in which the break
5123 built-in is used.
5124 Yash does not allow breaking such loops.
5126
5128 The cd built-in changes the working directory.
5129 Syntax
5131 · cd [-L|-P] [directory]
5132 Description
5134 The cd built-in changes the working directory to the directory
5135 specified by the operand.
5136 The pathname of the new working directory is assigned to the PWD
5138 variable, whose previous value is again assigned to the OLDPWD
5139 variable. The new PWD value will not contain any . or .. components
5140 except when the shell is in the POSIXly-correct mode and the new
5141 pathname begins with /...
5142 If directory is a relative path that does not start with ‘.’ or ‘..’,
5144 paths in the CDPATH variable are searched to find a new working
5145 directory. The search is done in a manner similar to the last step of
5146 command search, but a directory is sought instead of an executable
5147 regular file. If a new working directory was found from CDPATH, its
5148 pathname is printed to the standard output. If no applicable directory
5149 was found in the search, directory is simply treated as a pathname
5150 relative to the current working directory.
5151 If the working directory was successfully changed, the value of the
5153 YASH_AFTER_CD variable is executed as a command unless the shell is in
5154 the POSIXly-correct mode. If the variable is an array, its values are
5155 executed iteratively (cf. eval built-in).
5156 Options
5158 -L, --logical
5159 Symbolic links in the pathname of the new working directory are not
5160 resolved. The new value of the PWD may include pathname components
5161 that are symbolic links.
5162 -P, --physical
5164 Symbolic links in the pathname of the new working directory are
5165 resolved. The new value of the PWD variable never includes pathname
5166 components that are symbolic links.
5167 --default-directory=directory
5169 If this option is specified and the directory operand is omitted,
5170 the argument to this option is used for the directory operand. If
5171 the directory operand is specified, this option is ignored.
5172 The -L (--logical) and -P (--physical) options are mutually exclusive:
5174 only the last specified one is effective. If neither is specified, -L
5175 is assumed.
5176 Operands
5178 directory
5179 The pathname of the new working directory.
5180 If directory is a single hyphen (‘-’), the value of the OLDPWD
5182 variable is assumed for the new directory pathname, which is
5183 printed to the standard output.
5184 If directory is omitted, the working directory is changed to the
5186 directory specified by the --default-directory=... option. If that
5187 option is not specified either, the default is the home directory.
5188 Exit status
5190 The exit status of the cd built-in is zero if the working directory was
5191 successfully changed and non-zero if there was an error.
5192 Notes
5194 The cd built-in is a semi-special built-in.
5195 The POSIX standard does not define the use of the YASH_AFTER_CD
5197 variable or the --default-directory=... option. The standard does not
5198 allow using an option with a single hyphen operand.
5199 The exit status of the commands in the YASH_AFTER_CD variable does not
5201 affect that of the cd built-in.
5202
5204 The colon built-in does nothing.
5205 Syntax
5207 · : [argument...]
5208 Description
5210 The colon built-in does nothing. Any command line arguments are
5211 ignored.
5212 Exit status
5214 The exit status of the colon built-in is zero.
5215 Notes
5217 The colon built-in is a special built-in.
5218 Arguments are expanded and redirections are performed as usual. The
5220 colon and true built-ins have the same effect, but colon is a special
5221 built-in while true is a semi-special.
5222
5224 The command built-in executes or identifies a command.
5225 Syntax
5227 · command [-befp] command [argument...]
5228 · command -v|-V [-abefkp] command...
5230 Description
5232 Without the -v (--identify) or -V (--verbose-identify) option, the
5233 built-in executes command with arguments in the same manner as the last
5234 step of execution of simple commands. The command is treated as a
5235 built-in or external command or a function according to the options
5236 specified to the command built-in. The shell does not exit on argument
5237 syntax error etc. even if the command is a special built-in
5238 With the -v (--identify) option, command is identified. If the command
5240 is found in $PATH, its full pathname is printed. If it is a keyword,
5241 function, or built-in that is not found in $PATH, the command name is
5242 simply printed. If it is an alias, it is printed in the form like alias
5243 ll='ls -l'. If the command is not found, nothing is printed and the
5244 exit status is non-zero.
5245 The -V (--verbose-identify) option is similar to the -v (--identify)
5247 option, but the output format is more human-friendly.
5248 Options
5250 -a, --alias
5251 Search for the command as an alias. Must be used with the -v
5252 (--identify) or -V (--verbose-identify) option.
5253 -b, --builtin-command
5255 Search for the command as a built-in.
5256 -e, --external-command
5258 Search for the command as an external command.
5259 -f, --function
5261 Search for the command as a function.
5262 -k, --keyword
5264 Search for the command as a keyword. Must be used with the -v
5265 (--identify) or -V (--verbose-identify) option.
5266 -p, --standard-path
5268 Search the system’s default PATH instead of the current $PATH.
5269 -v, --identify
5271 Identify commands and print in the format defined in the POSIX
5272 standard.
5273 -V, --verbose-identify
5275 Identify commands and print in a human-friendly format.
5276 If none of the -a (--alias), -b (--builtin-command), -e
5278 (--external-command), -f (--function), and -k (--keyword) options is
5279 specified, the following defaults are assumed:
5280 Without the -v (--identify) or -V (--verbose-identify) option
5282 -b -e
5283 With the -v (--identify) or -V (--verbose-identify) option
5285 -a -b -e -f -k
5286 Operands
5288 command
5289 A command to be executed or identified.
5290 argument...
5292 Arguments passed to the executed command.
5293 Exit status
5295 The exit status of the command built-in is:
5296 Without the -v (--identify) or -V (--verbose-identify) option
5298 the exit status of the executed command.
5299 With the -v (--identify) or -V (--verbose-identify) option
5301 zero unless there is any error.
5302 Notes
5304 The command built-in is a semi-special built-in.
5305 In the POSIXly-correct mode, options other than -p, -v, and -V cannot
5307 be used and at most one command can be specified. The POSIX standard
5308 does not allow specifying both -v and -V together, but yash does (only
5309 the last specified one is effective).
5310
5312 The complete built-in generates completion candidates. This built-in
5313 can only be executed from completion functions during command line
5314 completion.
5315 Syntax
5317 · complete [-A pattern] [-R pattern] [-T] [-P prefix] [-S suffix]
5318 [-abcdfghjkuv] [[-O] [-D description] word...]
5319 Description
5321 The built-in generates completion candidates according to the specified
5322 arguments. No matter how candidates are generated, only candidates that
5323 match the word being completed are generated.
5324 Options
5326 -A pattern, --accept=pattern
5327 Only accept candidates that match the pattern specified by this
5328 option. When more than one of this option is specified, only
5329 candidates that match all of the patterns are generated.
5330 -D description, --description=description
5332 Give a description of the word candidates. The description is shown
5333 beside the candidates in the candidate list.
5334 -O, --option
5336 The candidates are treated as command line options. A hyphen is
5337 prepended to each candidate that is treated as an option.
5338 -P prefix, --prefix=prefix
5340 Ignore prefix of the word being completed when generating
5341 candidates. The specified prefix must be initial part of the word.
5342 If the word being completed is file:///home/user/docume for
5344 example, the command line complete -P file:// -f will generate
5345 pathname candidates that complete /home/user/docume.
5346 -R pattern, --reject=pattern
5348 Reject candidates that match the pattern specified by this option.
5349 When more than one of this option is specified, only candidates
5350 that match none of the patterns are generated.
5351 -S suffix, --suffix=suffix
5353 Append suffix to each generated candidate.
5354 -T, --no-termination
5356 Do not append a space after the word is completed. Without this
5357 option, a space is appended to the completed word so that you do
5358 not have to enter a space before the next word.
5359 Options that select candidate types
5361 -a, --alias
5362 Aliases. (same as --normal-alias --global-alias)
5363 --array-variable
5365 Arrays.
5366 --bindkey
5368 Line-editing commands the bindkey built-in accepts.
5369 -b, --builtin-command
5371 Built-in commands. (same as --special-builtin
5372 --semi-special-builtin --regular-builtin)
5373 -c, --command
5375 Commands. (same as --builtin-command --external-command
5376 --function)
5377 -d, --directory
5379 Directories.
5380 --dirstack-index
5382 Valid indices of the directory stack.
5383 --executable-file
5385 Executable regular files.
5386 --external-command
5388 External commands.
5389 -f, --file
5391 Files (including directories).
5392 --finished-job
5394 Job IDs of finished jobs.
5395 --function
5397 Functions.
5398 --global-alias
5400 Global aliases.
5401 -g, --group
5403 User groups.
5404 -h, --hostname
5406 Host names.
5407 -j, --job
5409 Job IDs.
5410 -k, --keyword
5412 Keywords.
5413 --normal-alias
5415 Normal aliases.
5416 --regular-builtin
5418 Regular built-in commands.
5419 --running-job
5421 Job IDs of jobs that are being executed.
5422 --scalar-variable
5424 Variables that are not arrays.
5425 --semi-special-builtin
5427 Semi-special built-in commands.
5428 --signal
5430 Signals.
5431 --special-builtin
5433 Special built-in commands.
5434 --stopped-job
5436 Job IDs of jobs that are suspended.
5437 -u, --username
5439 Users' log-in names.
5440 -v, --variable
5442 Variables.
5443 If the -d (--directory) option is specified without the -f (--file)
5445 option, the -S / -T options are assumed.
5446 Generated candidates for job IDs do not have leading percent signs
5448 (%). If the word being completed starts with a percent sign, the -P
5449 % option should be specified.
5450 Operands
5452 Operands are treated as completion candidates.
5453 Exit status
5455 The exit status of the built-in is zero if one or more candidates were
5456 generated, one if no candidates were generated, or larger than one if
5457 an error occurred.
5458 Notes
5460 The complete built-in is a semi-special built-in. In the POSIX
5461 standard, it is defined as a command with unspecified behavior.
5462
5464 The continue built-in skips an iteration of a loop being executed.
5465 Syntax
5467 · continue [nest]
5468 · continue -i
5470 Description
5472 When executed without the -i (--iteration) option, the built-in aborts
5473 the current iteration of for, while, or until loop and starts the next
5474 iteration of the loop. When executed in nested loops, it affects the
5475 nestth innermost loop. The default nest is one. If the number of
5476 currently executed nested loops is less than nest, the built-in affects
5477 the outermost loop.
5478 When executed with the -i (--iteration) option, the built-in aborts the
5480 current iteration of (innermost) iterative execution.
5481 Options
5483 -i, --iteration
5484 Skip an iterative execution instead of a loop.
5485 Operands
5487 nest
5488 The nestth innermost loop is affected. nest must be a positive
5489 integer.
5490 Exit status
5492 The exit status of the continue built-in is:
5493 · zero if loop iteration was successfully skipped.
5495 · that of the command that was executed just before the continue
5497 built-in if iterative execution was successfully skipped.
5498 Notes
5500 The continue built-in is a special built-in.
5501 The POSIX standard defines no options for the continue built-in; the
5503 built-in accepts no options in the POSIXly-correct mode.
5504 Treatment of currently executed loops that are not lexically enclosing
5506 the continue built-in is unspecified in POSIX. Examples of such loops
5507 include:
5508 · A loop invoking a function in which the continue built-in is used
5510 · A loop in which a trap action is executed in which the continue
5512 built-in is used
5513 Yash does not allow continuing such loops.
5515
5517 The dirs built-in prints the contents of the directory stack.
5518 Syntax
5520 · dirs [-cv] [index..]
5521 Description
5523 The directory stack is a feature that records history of working
5524 directories. You can use the pushd built-in to save a working directory
5525 in the directory stack, the popd built-in to recall the saved working
5526 directory, and the dirs built-in to see the stack contents. Those
5527 built-ins use the DIRSTACK array and the PWD variable to save the stack
5528 contents. Modifying the array means modifying the stack contents.
5529 Directory stack entries are indexed by signed integers. The entry of
5531 index +0 is the current working directory, +1 is the last saved
5532 directory, +2 is the second last, and so on. Negative indices are in
5533 the reverse order: the entry of index -0 is the first saved directory,
5534 -1 is the second, and -n is the current working directory if the stack
5535 has n entries,
5536 When executed without the -c (--clear) option, the dirs built-in prints
5538 the current contents of the directory stack to the standard output.
5539 With the -c (--clear) option, the built-in clears the directory stack.
5540 Options
5542 -c, --clear
5543 Clear the directory stack contents except for the current working
5544 directory, which has index +0.
5545 -v, --verbose
5547 Print indices when printing stack contents.
5548 Operands
5550 index
5551 The index of a stack entry to be printed.
5552 You can specify more than one index. If you do not specify any
5554 index, all the entries are printed.
5555 Exit status
5557 The exit status of the dirs built-in is zero unless there is any error.
5558 Notes
5560 The dirs built-in is a semi-special built-in. In the POSIX standard, it
5561 is defined as a command with unspecified behavior.
5562
5564 The disown built-in removes jobs.
5565 Syntax
5567 · disown [-a] [job...}
5568 Description
5570 The disown built-in removes the specified jobs from the job list. The
5571 removed jobs will no longer be job-controlled, but the job processes
5572 continue execution (unless they have been suspended).
5573 Options
5575 -a, --all
5576 Removes all jobs.
5577 Operands
5579 job
5580 The job ID of the job to be removed.
5581 You can specify more than one job ID. If you do not specify any job
5583 ID, the current job is removed. If the shell is not in the
5584 POSIXly-correct mode, the %-prefix of the job ID can be omitted.
5585 Exit status
5587 The exit status of the disown built-in is zero unless there is any
5588 error.
5589 Notes
5591 The disown built-in is a semi-special built-in. In the POSIX standard,
5592 it is defined as a command with unspecified behavior.
5593
5595 The dot built-in reads a file and executes commands in it.
5596 Syntax
5598 · . [-AL] file [argument...]
5599 Description
5601 The dot built-in reads the specified file, parses its contents as
5602 commands, and executes them in the current command execution
5603 environment.
5604 If arguments are specified, positional parameters are temporarily set
5606 to them. The positional parameters will be restored when the dot
5607 built-in finishes. If no arguments are specified, the positional
5608 parameters are not changed.
5609 If file does not contain any slashes, the shell searches $PATH for a
5611 readable (but not necessarily executable) shell script file whose name
5612 is file in the same manner as command search. If no such file was
5613 found, the shell searches the current working directory for a file
5614 unless in the POSIXly-correct mode. To ensure that the file in the
5615 current working directory is used, start file with ‘./’.
5616 Options
5618 -A, --no-alias
5619 Disable alias substitution while parsing.
5620 -L, --autoload
5622 Search $YASH_LOADPATH instead of $PATH, regardless of whether file
5623 contains slashes. The file value is not considered relative to the
5624 current working directory.
5625 The dot built-in treats as operands any command line arguments after
5627 the first operand.
5628 Operands
5630 file
5631 The pathname of a file to be read.
5632 arguments...
5634 Strings to which positional parameters are set while execution.
5635 Exit status
5637 The exit status of the dot built-in is that of the last command
5638 executed. The exit status is zero if the file contains no commands to
5639 execute and non-zero if a file was not found or could not be opened.
5640 Notes
5642 The dot built-in is a special built-in.
5643 A non-interactive shell immediately exits with a non-zero exit status
5645 if the dot built-in fails to find or open a file to execute.
5646 The POSIX standard defines no options for the dot built-in; the
5648 built-in accepts no options in the POSIXly-correct mode.
5649 The POSIX standard does not define the arguments... operands. It is an
5651 error to specify the arguments... operands in the POSIXly-correct mode.
5652
5654 The echo built-in prints its arguments.
5655 Syntax
5657 · echo [string...]
5658 The built-in treats all command line arguments as operands except for
5660 the options described below. Any word that cannot be parsed as an
5661 acceptable option is treated as an operand. Options must precede all
5662 operands. Syntax errors never happen in the echo built-in.
5663 Description
5665 The echo built-in prints the operand strings followed by a newline to
5666 the standard output. The strings are each separated by a space.
5667 Escape sequences
5669 The ECHO_STYLE variable and the -e option enable escape sequences
5670 that are replaced with corresponding characters:
5671 \a
5673 Bell character (ASCII code: 7)
5674 \b
5676 Backspace (ASCII code: 8)
5677 \c
5679 Nothing. After this escape sequence, no characters are printed
5680 at all.
5681 \e
5683 Escape character (ASCII code: 27)
5684 \f
5686 Form feed character (ASCII code: 12)
5687 \n
5689 Newline character (ASCII code: 10)
5690 \r
5692 Carriage return character (ASCII code: 13)
5693 \t
5695 Horizontal tab character (ASCII code: 9)
5696 \v
5698 Vertical tab character (ASCII code: 11)
5699 \\
5701 Backslash
5702 \0xxx
5704 Character whose code is xxx, where xxx is an octal number of at
5705 most three digits.
5706 When escape sequences are not enabled, they are just printed
5708 intact.
5709 ECHO_STYLE variable
5711 The ECHO_STYLE variable defines which options are accepted and
5712 whether escape sequences are enabled by default. The variable value
5713 should be set to one of the following:
5714 SYSV, XSI
5716 No options are accepted. Escape sequences are always enabled.
5717 BSD
5719 The -n option is accepted. Escape sequences are never enabled.
5720 GNU
5722 The -n, -e, and -E options are accepted. Escape sequences are
5723 not enabled by default, but can be enabled by the -e option.
5724 ZSH
5726 The -n, -e, and -E options are accepted. Escape sequences are
5727 enabled by default, but can be disabled by the -E option.
5728 DASH
5730 The -n option is accepted. Escape sequences are always enabled.
5731 RAW
5733 No options are accepted. Escape sequences are never enabled.
5734 When the ECHO_STYLE variable is not set, it defaults to SYSV.
5736 Options
5738 -n
5739 Do not print a newline at the end.
5740 -e
5742 Enable escape sequences.
5743 -E
5745 Disable escape sequences.
5746 Exit status
5748 The exit status of the echo built-in is zero unless there is any error.
5749 Notes
5751 The POSIX standard does not define the ECHO_STYLE variable nor any
5752 options for the built-in. According to POSIX, the behavior of the
5753 built-in is implementation-defined when the first argument is -n or
5754 when any argument contains a backslash. For maximum portability, the
5755 printf built-in should be preferred over the echo built-in.
5756 Although many values for the ECHO_STYLE variable are defined on the
5758 basis of other existing implementations, yash is not intended to
5759 exactly imitate those originals. Zsh’s echo built-in interprets a
5760 single hyphen argument as a separator between options and operands.
5761 Yash does not support such use of hyphen.
5762
5764 The eval built-in evaluates operands as commands.
5765 Syntax
5767 · eval [-i] [command...]
5768 The eval built-in requires that all options precede operands. Any
5770 command line arguments after the first operand are all treated as
5771 operands.
5772 Description
5774 The eval parses operands as commands and executes them in the current
5775 command execution environment.
5776 When executed without the -i (--iteration) option, all the operands are
5778 concatenated into one string (with a space inserted between each
5779 operand) and parsed/executed at once.
5780 With the -i (--iteration) option, the built-in performs iterative
5782 execution: operands are parsed/executed one by one. If the continue
5783 built-in is executed with the -i (--iteration) option during the
5784 iterative execution, the execution of the current operand is aborted
5785 and the next operand is parsed/executed immediately. The break built-in
5786 with the -i (--iteration) option is similar but the remaining operands
5787 are not parsed/executed. The value of the ? special parameter is saved
5788 before the iterative execution is started. The parameter value is
5789 restored to the saved one after each iteration.
5790 Options
5792 -i, --iteration
5793 Perform iterative execution.
5794 Operands
5796 command
5797 A string that is parsed and executed as commands.
5798 Exit status
5800 The exit status is zero if no command was specified or command
5801 contained no actual command that can be executed. Otherwise, that is,
5802 if the eval built-in executed one or more commands, the exit status of
5803 the eval built-in is that of the last executed command.
5804 Notes
5806 The eval built-in is a special built-in.
5807 The POSIX standard defines no options for the eval built-in; the
5809 built-in accepts no options in the POSIXly-correct mode.
5810
5812 The exec built-in replaces the shell process with another external
5813 command.
5814 Syntax
5816 · exec [-cf] [-a name] [command [argument...]]
5817 The exec built-in requires that all options precede operands. It is
5819 important so that options to the exec built-in are not confused with
5820 options to command. Any command line arguments after command are
5821 treated as arguments.
5822 Description
5824 When the exec built-in is executed with command, the shell executes
5825 command with arguments in a manner similar to the last step of
5826 execution of a simple command. The differences are that command is
5827 always treated as an external command ignoring any existing functions
5828 and built-ins and that the exec system call that starts the external
5829 command is called in the current command execution environment instead
5830 of a subshell, replacing the shell process with the new command
5831 process.
5832 If the shell is in the POSIXly-correct mode or not interactive, failure
5834 in execution of command causes the shell to exit immediately.
5835 If an interactive shell that is not in the POSIXly-correct mode has a
5837 stopped job, the shell prints a warning message and refuses to execute
5838 command. Once the shell process is replaced with an external command,
5839 information about the shell’s jobs is lost, so you will have to resume
5840 or kill the stopped jobs by sending signals by hand. To force the shell
5841 to execute command regardless, specify the -f (--force) option.
5842 When executed without command, the built-in does nothing. As a side
5844 effect, however, redirection applied to the built-in remains in the
5845 current command execution environment even after the built-in finished.
5846 Options
5848 -a name, --as=name
5849 Pass name, instead of command, to the external command as its name.
5850 -c, --clear
5852 Pass to the external command only variables that are assigned in
5853 the simple command in which the built-in is being executed. Other
5854 environment variables are not passed to the command.
5855 -f, --force
5857 Suppress warnings that would prevent command execution.
5858 Operands
5860 command
5861 An external command to be executed.
5862 argument...
5864 Arguments to be passed to the command.
5865 Exit status
5867 If the shell process was successfully replaced with the external
5868 command, there is no exit status since the shell process no longer
5869 exists.
5870 The exit status is:
5872 · 127 if the command was not found,
5874 · 126 if the command was found but could not be executed, and
5876 · zero if no command was specified.
5878 Notes
5880 The exec built-in is a special built-in.
5881 The POSIX standard defines no options for the exec built-in; the
5883 built-in accepts no options in the POSIXly-correct mode.
5884
5886 The exit built-in causes the shell process to exit.
5887 Syntax
5889 · exit [-f] [exit_status]
5890 Description
5892 The exit built-in causes the current shell (or subshell) process to
5893 exit.
5894 If an interactive shell has a stopped job, the shell prints a warning
5896 message and refuses to exit. To force the shell to exit regardless,
5897 specify the -f (--force) option or execute the built-in twice in a row.
5898 If an EXIT trap has been set, the shell executes the trap before
5900 exiting.
5901 Options
5903 -f, --force
5904 Suppress warnings that would prevent the shell from exiting.
5905 Operands
5907 exit_status
5908 A non-negative integer that will be the exit status of the exiting
5909 shell.
5910 If this operand is omitted, the exit status of the shell will be
5912 that of the last command executed before the exit built-in (but, if
5913 the built-in is executed during a trap, the exit status will be
5914 that of the last command before the trap is entered).
5915 If exit_status is 256 or larger, the actual exit status will be the
5917 remainder of exit_status divided by 256.
5918 Exit status
5920 Because the built-in causes the shell to exit, there is no exit status
5921 of the built-in.
5922 As an exception, if the shell refused to exit, the exit status of the
5924 built-in is non-zero.
5925 Notes
5927 The exit built-in is a special built-in.
5928 The POSIX standard defines no options for the exit built-in; the
5930 built-in accepts no options in the POSIXly-correct mode.
5931 The POSIX standard provides that the exit_status operand should be
5933 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
5934 an extension.
5935 If the built-in is executed during an EXIT trap, the shell just exits
5937 without executing the trap again. If exit_status was not specified, the
5938 exit status of the shell is what the exit status would be if the trap
5939 had not been set. See also Termination of the shell.
5940
5942 The export built-in marks variables for export to child processes.
5943 Syntax
5945 · export [-prX] [name[=value]...]
5946 Description
5948 The export built-in is equivalent to the typeset built-in with the -gx
5949 option.
5950 Notes
5952 The export built-in is a special built-in.
5953 The POSIX standard defines the -p option only; other options cannot be
5955 used in the POSIXly-correct mode. The POSIX does not allow using the
5956 option together with operands.
5957
5959 The false built-in does nothing unsuccessfully.
5960 Syntax
5962 · false
5963 Description
5965 The false built-in does nothing. Any command line arguments are
5966 ignored.
5967 Exit status
5969 The exit status of the false built-in is non-zero.
5970 Notes
5972 The false built-in is a semi-special built-in.
5973
5975 The fc built-in re-executes or prints commands from command history.
5976 Syntax
5978 · fc [-qr] [-e editor] [start [end]]
5979 · fc -s[q] [old=new] [start]
5981 · fc -l[nrv] [start [end]]
5983 Description
5985 When executed without the -l (--list) option, the built-in executes the
5986 commands in the command history range specified by the operands. If the
5987 -s (--silent) option is not specified, the shell invokes an editor
5988 which allows you to edit the commands before they are executed. The
5989 commands are executed when you quit the editor. If the -s (--silent)
5990 option is specified, the commands are immediately executed. In either
5991 case, the executed commands are printed to the standard output and
5992 added to the history.
5993 When executed with the -l (--list) option, the built-in prints the
5995 commands in the command history range specified by the operands. By
5996 default, commands are printed with their history entry numbers, but
5997 output format can be changed using the -n (--no-numbers)) and -v
5998 (--verbose) options.
5999 Options
6001 -e editor, --editor=editor
6002 Specify an editor that is used to edit commands.
6003 If this option is not specified, the value of the FCEDIT variable
6005 is used. If the variable is not set either, ed is used.
6006 -l, --list
6008 Print command history entries.
6009 -n, --no-numbers
6011 Don’t print entry numbers when printing history entries.
6012 -q, --quiet
6014 Don’t print commands before executing.
6015 -r, --reverse
6017 Reverse the order of command entries in the range.
6018 -s, --silent
6020 Execute commands without editing them.
6021 -v, --verbose
6023 Print execution time before each history entry when printing.
6024 Operands
6026 start and end
6027 The start and end operands specify a range of command history
6028 entries that are executed or printed. If one of the operands is an
6029 integer, it is treated as a history entry number. A negative
6030 integer means the nth most recent entry where n is the absolute
6031 value of the integer. If one of the operands is not an integer, it
6032 is treated as part of a command string: the most recent entry that
6033 starts with the string is selected as the start or end of the
6034 range.
6035 If the first entry of the range that is specified by start is newer
6037 than the last entry of the range that is specified by end, the
6038 range is reversed as if the -r (--reverse) option was specified.
6039 (If the option is already specified, it is cancelled.)
6040 The default values for start and end are:
6042 ┌──────┬─────────┬───────────────┐
6044 │ │ with -l │ without -l │
6045 ├──────┼─────────┼───────────────┤
6046 │start │ -16 │ -1 │
6047 ├──────┼─────────┼───────────────┤
6048 │end │ -16 │ same as start │
6049 └──────┴─────────┴───────────────┘
6050 old=new
6052 An operand of this format replaces part of the command string. If
6053 the command string contains old, it is replaced with new and the
6054 new string is executed. Only the first occurrence of old is
6055 replaced.
6056 Exit status
6058 If commands was executed, the exit status of the fc built-in is that of
6059 the last executed command. Otherwise, the exit status is zero unless
6060 there is any error.
6061 Notes
6063 The fc built-in is a semi-special built-in.
6064 The POSIX standard does not define the -q (--quiet) or -v (--verbose)
6066 options, so they cannot be used in the POSIXly-correct mode.
6067 Command history cannot be modified during line-editing.
6069
6071 The fg built-in resumes a job in the foreground.
6072 Syntax
6074 · fg [job...]
6075 Description
6077 The fg built-in brings the specified job to the foreground and sends
6078 the SIGCONT signal to the job. As a result, the job is resumed in the
6079 foreground (if it has been suspended). The built-in then waits for the
6080 job to finish and returns the exit status of it.
6081 The name of the job is printed when the job is resumed. When not in the
6083 POSIXly-correct mode, the job number is also printed.
6084 The built-in can be used only when job control is enabled.
6086 Operands
6088 job
6089 The job ID of the job to be resumed.
6090 If more than one job is specified, they are resumed in order, one
6092 at a time. The current job is resumed if none is specified.
6093 The percent sign (%) at the beginning of a job ID can be omitted if
6095 the shell is not in the POSIXly-correct mode.
6096 Exit status
6098 The exit status of the fg built-in is that of the (last) job resumed.
6099 The exit status is non-zero when there was some error.
6100 Notes
6102 The fg built-in is a semi-special built-in.
6103 You cannot specify more than one job in the POSIXly-correct mode.
6105
6107 The getopts built-in parses command options.
6108 Syntax
6110 · getopts optionlist variable [argument...]
6111 Description
6113 The getopts built-in parses single-character options that appear in
6114 arguments. Each time the built-in is invoked, it parses one option and
6115 assigns the option character to variable.
6116 The optionlist operand is a list of option characters that should be
6118 accepted by the parser. In optionlist, an option that takes an argument
6119 should be specified as the option character followed by a colon. For
6120 example, if you want the -a, -b and -c options to be parsed and the -b
6121 option to take an argument, then optionlist should be ab:c.
6122 When an option that takes an argument is parsed, the argument is
6124 assigned to the OPTARG variable.
6125 When an option that is not specified in optionlist is found or when an
6127 option argument is missing, the result depends on the first character
6128 of optionlist:
6129 · If optionlist starts with a colon, the option character is assigned
6131 to the OPTARG variable and variable is set to either ? (when the
6132 option is not in optionlist) or : (when the option argument is
6133 missing).
6134 · Otherwise, variable is set to ?, the OPTARG variable is unset, and
6136 an error message is printed.
6137 The built-in parses one option for each execution. For all options in a
6139 set of command line arguments to be parsed, the built-in has to be
6140 executed repeatedly with the same arguments. The built-in uses the
6141 OPTIND variable to remember which argument should be parsed next. When
6142 the built-in is invoked for the first time, the variable value must be
6143 1, which is the default value. You must not modify the variable until
6144 all the options have been parsed, when the built-in sets the variable
6145 to the index of the first operand in arguments. (If there are no
6146 operands, it will be set to the number of arguments plus one.)
6147 When you want to start parsing a new set of arguments, you have to
6149 reset the OPTIND variable to 1 beforehand.
6150 Operands
6152 optionlist
6153 A list of options that should be accepted as valid options in
6154 parsing.
6155 variable
6157 The name of a variable the result is to be assigned to.
6158 arguments
6160 Command line arguments that are to be parsed.
6161 When no arguments are given, the positional parameters are parsed.
6163 Exit status
6165 If an option is found, whether or not it is specified in optionlist,
6166 the exit status is zero. If there is no more option to be parsed, the
6167 exit status is non-zero.
6168 Example
6170 aopt=false bopt= copt=false
6171 while getopts ab:c opt
6172 do
6173 case $opt in
6174 a) aopt=true ;;
6175 b) bopt=$OPTARG ;;
6176 c) copt=true ;;
6177 \?) return 2 ;;
6178 esac
6179 done
6180 if $aopt; then echo Option -a specified; fi
6181 if [ -n "$bopt" ]; then echo Option -b $bopt specified; fi
6182 if $copt; then echo Option -c specified; fi
6183 shift $((OPTIND - 1))
6184 echo Operands are: $*
6185 Notes
6187 In arguments that are parsed, options must precede operands. The
6188 built-in ends parsing when it encounters the first operand.
6189 The getopts built-in is a semi-special built-in.
6191 The POSIX standard does not specify what will happen when the OPTIND
6193 variable is assigned a value other than 1.
6194 In the POSIXly-correct mode, option characters in optionlist must be
6196 alphanumeric.
6197
6199 The hash built-in remembers, forgets, or reports command locations.
6200 Syntax
6202 · hash command...
6203 · hash -r [command...]
6205 · hash [-a]
6207 · hash -d user...
6209 · hash -dr [user...]
6211 · hash -d
6213 Description
6215 When executed with commands but without options, the built-in
6216 immediately performs command path search and caches commands' full
6217 paths.
6218 When executed with the -r (--remove) option, it removes the paths of
6220 commands (or all cached paths if none specified) from the cache.
6221 When executed without options or commands, it prints the currently
6223 cached paths to the standard output.
6224 With the -d (--directory) option, the built-in does the same things to
6226 the home directory cache, rather than the command path cache. Cached
6227 home directory paths are used in tilde expansion.
6228 Options
6230 -a, --all
6231 Print all cached paths.
6232 Without this option, paths for built-ins are not printed.
6234 -d, --directory
6236 Affect the home directory cache instead of the command path cache.
6237 -r, --remove
6239 Remove cached paths.
6240 Operands
6242 command
6243 The name of an external command (that does not contain any slash).
6244 user
6246 A user name.
6247 Exit status
6249 The exit status of the hash built-in is zero unless there is any error.
6250 Notes
6252 The shell automatically caches command and directory paths when
6253 executing a command or performing tilde expansion, so normally there is
6254 no need to use this built-in explicitly to cache paths.
6255 Assigning a value to the PATH variable removes all command paths from
6257 the cache as if hash -r was executed.
6258 The POSIX standard defines the -r option only: other options cannot be
6260 used in the POSIXly-correct mode.
6261 The hash built-in is a semi-special built-in.
6263
6265 The help built-in prints usage of built-ins.
6266 Syntax
6268 · help [built-in...]
6269 Description
6271 The help built-in prints a description of built-ins.
6272 Operands
6274 built-ins
6275 Names of built-ins.
6276 Exit status
6278 The exit status of the help built-in is zero unless there is any error.
6279 Notes
6281 The help built-in is a semi-special built-in. In the POSIX standard, it
6282 is defined as a command with unspecified behavior.
6283 Many built-ins of yash accept the --help option that prints the same
6285 description.
6286
6288 The history built-in prints or edits command history.
6289 Syntax
6291 · history [-cF] [-d entry] [-s command] [-r file] [-w file] [count]
6292 Description
6294 The history built-in prints or edits command history.
6295 When executed with an option, the built-in edits history according to
6297 the option. If more than one option is specified, each option is
6298 processed in order.
6299 When executed with the count operand, the built-in prints the most
6301 recent count history entries to the standard output in the same manner
6302 as the fc built-in.
6303 When executed with neither options nor operands, the built-in prints
6305 the whole history.
6306 Options
6308 -c, --clear
6309 Clear all history entries completely.
6310 -d entry, --delete=entry
6312 Delete the specified entry. The entry should be specified in the
6313 same manner as the start and end operands of the fc built-in.
6314 -F, --flush-file
6316 Rebuild the history file. This operation removes unused old data
6317 from the file.
6318 -r file, --read=file
6320 Read command lines from file and add them to the history. The file
6321 contents are treated as lines of simple text.
6322 -s command, --set=command
6324 Add command as a new history entry after removing the most recent
6325 entry.
6326 -w file, --write=file
6328 Write the whole history to file. Any existing data in the file will
6329 be lost. The output format is lines of simple text, each of which
6330 is a command string.
6331 Operands
6333 count
6334 The number of entries to be printed.
6335 Exit status
6337 The exit status of the history built-in is zero unless there is any
6338 error.
6339 Notes
6341 The history built-in is a semi-special built-in. In the POSIX standard,
6342 it is defined as a command with unspecified behavior.
6343 Command history cannot be modified during line-editing.
6345
6347 The jobs built-in reports job status.
6348 Syntax
6350 · jobs [-lnprs] [job...]
6351 Description
6353 The jobs built-in prints information of jobs the shell is currently
6354 controlling.
6355 By default, the following information is printed for each job, line by
6357 line:
6358 · the job number,
6360 · the + or - symbol if the job is the current or previous job,
6362 respectively,
6363 · the status, and
6365 · the command string.
6367 Options
6369 -l, --verbose
6370 Print the process ID, status, and command string for each process
6371 in the jobs.
6372 -n, --new
6374 Print new jobs only: jobs whose status has never been reported
6375 since the status changed.
6376 -p, --pgid-only
6378 Print process group IDs of jobs only.
6379 -r, --running-only
6381 Print running jobs only.
6382 -s, --stopped-only
6384 Print stopped jobs only.
6385 Operands
6387 jobs
6388 The job IDs of jobs to be reported. When no job is specified, all
6389 jobs under the shell’s control are reported.
6390 The percent sign (%) at the beginning of a job ID can be omitted if
6392 the shell is not in the POSIXly-correct mode.
6393 Exit status
6395 The exit status of the jobs built-in is zero unless there is any error.
6396 Notes
6398 The jobs built-in is a semi-special built-in.
6399 The POSIX standard defines the -l and -p options only: other options
6401 cannot be used in the POSIXly-correct mode. In the POSIXly-correct
6402 mode, the effect of the -l option is different in that status is
6403 reported for each job rather than for each process.
6404 The process group ID of a job executed by yash is equal to the process
6406 ID of the first command of the pipeline that forms the job.
6407
6409 The kill built-in sends a signal to processes.
6410 Syntax
6412 · kill [-signal|-s signal|-n signal] process...
6413 · kill -l [-v] [signal...]
6415 The kill built-in requires that all options precede operands. Any
6417 command line arguments after the first operand are all treated as
6418 operands.
6419 Description
6421 When executed without the -l option, the built-in sends a signal to
6422 processes. The signal sent can be specified by option. The SIGTERM
6423 signal is sent if no signal is specified.
6424 When executed with the -l option, the built-in prints information of
6426 signals to the standard output. If no signal is specified, information
6427 of all signals is printed.
6428 Options
6430 Signal-specifying options
6431 -signal, -s signal, -n signal
6432 A signal-specifying option specifies a signal to be sent to
6433 processes. signal can be specified by name or number. If
6434 number 0 is specified, the built-in checks if a signal could be
6435 sent to the processes but no signal is actually sent. Signal
6436 names are case-insensitive.
6437 You can specify at most one signal-specifying option at a time.
6439 Other options
6441 -l
6442 Print signal information instead of sending a signal.
6443 -v
6445 Print more signal information.
6446 Without this option, the built-in prints the signal name only.
6448 This option adds the signal number and a short description.
6449 When the -v option is specified, the -l option can be omitted.
6451 Operands
6453 processes
6454 Specify processes to which a signal is sent.
6455 Processes can be specified by the process ID, the process group ID,
6457 or the job ID. The process group ID must be prefixed with a hyphen
6458 (-) so that it is not treated as a process ID.
6459 When 0 is specified as process, the signal is sent to the process
6461 group to which the shell process belongs. When -1 is specified, the
6462 signal is sent to all processes on the system.
6463 signal
6465 Specify a signal of which information is printed.
6466 The signal can be specified by the name, the number, or the exit
6468 status of a command that was killed by the signal.
6469 Exit status
6471 The exit status of the kill built-in is zero unless there is any error.
6472 If the signal was sent to at least one process, the exit status is zero
6473 even if the signal was not sent to all of the specified processes.
6474 Notes
6476 The kill built-in is a semi-special built-in.
6477 Command arguments that start with a hyphen should be used with care.
6479 The command kill -1 -2, for example, sends signal 1 to process group 2
6480 since -1 is treated as a signal-specifying option and -2 as an operand
6481 that specifies a process group. The commands kill -- -1 -2 and kill
6482 -TERM -1 -2, on the other hand, treats both -1 and -2 as operands.
6483 The POSIX standard does not define the -n or -v options, so they cannot
6485 be used in the POSIXly-correct mode. The standard does not allow
6486 specifying a signal number as the argument of the -s option or a signal
6487 name as the signal operand.
6488 The standard requires signal names to be specified without the SIG
6490 prefix, like INT and QUIT. If the shell is not in the POSIXly-correct
6491 mode, the built-in accepts SIG-prefixed signal names as well.
6492
6494 The local built-in prints or sets local variables.
6495 Syntax
6497 · local [-rxX] [name[=value]...]
6498 Description
6500 The local built-in is equivalent to the typeset built-in except that
6501 the -f (--functions) and -g (--global) options cannot be used.
6502 Notes
6504 The local built-in is a semi-special built-in. In the POSIX standard,
6505 it is defined as a command with unspecified behavior.
6506
6508 The popd built-in pops a directory from the directory stack.
6509 Syntax
6511 · popd [index]
6512 Description
6514 The popd built-in removes the last entry from the directory stack,
6515 returning to the previous working directory. If index is given, the
6516 entry specified by index is removed instead of the last one.
6517 Operands
6519 index
6520 The index of a directory stack entry you want to remove.
6521 If omitted, +0 (the last entry) is assumed.
6523 Exit status
6525 The exit status of the popd built-in is zero unless there is any error.
6526 Notes
6528 It is an error to use this built-in when there is only one directory
6529 stack entry.
6530 The popd built-in is a semi-special built-in. In the POSIX standard, it
6532 is defined as a command with unspecified behavior.
6533
6535 The printf built-in prints formatted values.
6536 Syntax
6538 · printf format [value...]
6539 Description
6541 The printf built-in formats values according to format and prints them
6542 to the standard output. Unlike the echo built-in, the printf built-in
6543 does not print a newline automatically.
6544 The formatting process is very similar to that of the printf function
6546 in the C programming language. You can use conversion specifications
6547 (which start with %) and escape sequences (which start with \) in
6548 format. Any other characters that are not part of a conversion
6549 specification or escape sequence are printed literally.
6550 Conversion specifications
6552 A conversion specification starts with a percent sign (%).
6553 A conversion specification except %% consumes a value, which is
6555 formatted according to the specification and printed. Each
6556 conversion specification consumes one value in the order of
6557 appearance. If there are more values than conversion
6558 specifications, the entire format is re-processed until all the
6559 values are consumed. If a value to be consumed is missing, it is
6560 assumed to be an empty string (if the specification requires a
6561 string) or zero (if a number). If no values are given, format is
6562 processed just once.
6563 Available conversion specifications are:
6565 %d, %i
6567 prints a signed integer in decimal
6568 %u
6570 prints an unsigned integer in decimal
6571 %o
6573 prints an unsigned integer in octal
6574 %x
6576 prints an unsigned integer in lowercase hexadecimal
6577 %X
6579 prints an unsigned integer in uppercase hexadecimal
6580 %f
6582 prints a floating-point number in lowercase
6583 %F
6585 prints a floating-point number in uppercase
6586 %e
6588 prints a floating-point number with exponent in lowercase
6589 %E
6591 prints a floating-point number with exponent in uppercase
6592 %g
6594 the same as %f or %e, automatically selected
6595 %G
6597 the same as %F or %E, automatically selected
6598 %c
6600 prints the first character of string
6601 %s
6603 prints a string
6604 %b
6606 prints a string (recognizing escape sequences like the echo
6607 built-in)
6608 %%
6610 prints a percent sign (%)
6611 For %g and %G, the specification that is actually used is %f or %F
6613 if the exponent part is between -5 and the precision (exclusive);
6614 %e or %E otherwise.
6615 In a conversion specification except %%, the leading percent sign
6617 may be followed by flags, field width, and/or precision in this
6618 order.
6619 The flags are a sequence of any number of the following characters:
6621 Minus sign (-)
6623 With this flag, spaces are appended to the formatted value to
6624 fill up to the field width. Otherwise, spaces are prepended.
6625 Plus sign (+)
6627 A plus or minus sign is always prepended to a number.
6628 Space ( )
6630 A space is prepended to a formatted number if it has no plus or
6631 minus sign.
6632 Hash sign (#)
6634 The value is formatted in an alternative form: For %o, the
6635 printed octal integer has at least one leading zero. For %x and
6636 %X, a non-zero integer is formatted with 0x and 0X prefixes,
6637 respectively. For %e, %E, %f, %F, %g, and %G, a decimal mark
6638 (a.k.a. radix character) is always printed even if the value is
6639 an exact integer. For %g and %G, the printed number has at
6640 least one digit in the fractional part.
6641 Zero (0)
6643 Zeros are prepended to a formatted number to fill up to the
6644 field width. This flag is ignored if the minus flag is
6645 specified or if the conversion specification is %d, %i, %u, %o,
6646 %x, or %X with a precision.
6647 A field width is specified as a decimal integer that has no leading
6649 zeros.
6650 A field width defines a minimum byte count of a formatted value. If
6652 the formatted value does not reach the minimum byte count, so many
6653 spaces are prepended that the printed value has the specified byte
6654 count.
6655 A precision is specified as a period (.) followed by a decimal
6657 integer. If the integer is omitted after the period, the precision
6658 is assumed to be zero.
6659 For conversion specifications %d, %i, %u, %o, %x, and %X, a
6661 precision defines a minimum digit count. If the formatted integer
6662 does not reach the minimum digit count, so many zeros are prepended
6663 that the printed integer has the specified number of digits. The
6664 default precision is one for these conversion specifications.
6665 For conversion specifications %e, %E, %f, and %F, a precision
6667 defines the number of digits after the decimal mark. The default
6668 precision is six for these conversion specifications.
6669 For conversion specifications %g, and %G, a precision defines a
6671 maximum number of significant digits in the printed value. The
6672 default precision is six for these conversion specifications.
6673 For conversion specifications %s, and %b, a precision defines a
6675 maximum byte count of the printed string. The default precision is
6676 infinity for these conversion specifications.
6677 In the conversion specification %08.3f, the zero flag is specified,
6679 the field width is 8, and the precision is 3. If this specification
6680 is applied to value 12.34, the output will be 0012.340.
6681 Escape sequences
6683 The following escape sequences are recognized in format:
6684 \a
6686 Bell character (ASCII code: 7)
6687 \b
6689 Backspace (ASCII code: 8)
6690 \f
6692 Form feed character (ASCII code: 12)
6693 \n
6695 Newline character (ASCII code: 10)
6696 \r
6698 Carriage return character (ASCII code: 13)
6699 \t
6701 Horizontal tab character (ASCII code: 9)
6702 \v
6704 Vertical tab character (ASCII code: 11)
6705 \\
6707 Backslash
6708 \"
6710 Double quotation
6711 \'
6713 Single quotation (apostrophe)
6714 \xxx
6716 Character whose code is xxx, where xxx is an octal number of at
6717 most three digits.
6718 Operands
6720 format
6721 A string that defines how values should be formatted.
6722 values
6724 Values that are formatted according to format.
6725 A value is either a number or a string.
6727 When a numeric value is required, value can be a single or double
6729 quotation followed by a character, instead of a normal number. For
6730 example, the command printf '%d' '"3' will print 51 on a typical
6731 environment where character 3 has character code 51.
6732 Exit status
6734 The exit status of the printf built-in is zero unless there is any
6735 error.
6736 Notes
6738 The POSIX standard does not precisely define how multibyte characters
6739 should be handled by the built-in. When you use the %s conversion
6740 specification with precision or the %c conversion specification, you
6741 may obtain unexpected results if the formatted value contains a
6742 character that is represented by more than one byte. Yash never prints
6743 only part of the bytes that represent a single multibyte character
6744 because all multibyte characters are converted to wide characters when
6745 processed in the shell.
6746 If the shell is not in the POSIXly-correct mode and the “long double”
6748 floating-point arithmetic is supported on the running system, then
6749 “long double” is used for floating-point conversion specifications.
6750 Otherwise, “double” is used.
6751
6753 The pushd built-in pushes a directory into the directory stack.
6754 Syntax
6756 · pushd [-L|-P] [directory]
6757 Description
6759 The pushd built-in changes the working directory to directory in the
6760 same manner as the cd built-in and adds it to the directory stack. If
6761 the working directory could not be changed successfully, the stack is
6762 not modified.
6763 Options
6765 The pushd built-in accepts the following option as well as the options
6766 that can be used for the cd built-in:
6767 --remove-duplicates
6769 If the new working directory has already been in the directory
6770 stack, the existing entry is removed from the stack before the new
6771 directory is pushed into the stack.
6772 Operands
6774 directory
6775 The pathname of the new working directory.
6776 If directory is a single hyphen (‘-’), the value of the OLDPWD
6778 variable is assumed for the new directory pathname, which is
6779 printed to the standard output.
6780 If directory is an integer with a plus or minus sign, it is
6782 considered as an entry index of the directory stack. The entry is
6783 removed from the stack and then pushed to the stack again.
6784 If directory is omitted, the working directory is changed to the
6786 directory specified by the --default-directory=... option. If that
6787 option is not specified either, the default is index +1.
6788 Exit status
6790 The exit status of the pushd built-in is zero unless there is any
6791 error.
6792 Notes
6794 The pushd built-in is a semi-special built-in. In the POSIX standard,
6795 it is defined as a command with unspecified behavior.
6796
6798 The pwd built-in prints the current working directory.
6799 Syntax
6801 · pwd [-L|-P]
6802 Description
6804 The pwd built-in prints an absolute path to the shell’s current working
6805 directory to the standard output.
6806 Options
6808 -L, --logical
6809 If the value of the PWD variable is an absolute path to the shell’s
6810 working directory and the path does not contain any . or ..
6811 components, then the path is printed. Otherwise, the printed path
6812 is the same as when the -P option is specified.
6813 -P, --physical
6815 The printed path does not contain any . or .. components,
6816 symbolic link components, or redundant slashes.
6817 The -L (--logical) and -P (--physical) options are mutually exclusive:
6819 only the last specified one is effective. If neither is specified, -L
6820 is assumed.
6821 Exit status
6823 The exit status of the pwd built-in is zero unless there is any error.
6824 Notes
6826 The pwd built-in is a semi-special built-in.
6827
6829 The read built-in reads a line from the standard input.
6830 Syntax
6832 · read [-Aer] [-P|-p] variable...
6833 Description
6835 The read built-in reads a line of string from the standard input and
6836 assigns it to the specified variables.
6837 If the -r (--raw-mode) option is specified, all characters in the line
6839 are treated literally.
6840 If the -r (--raw-mode) option is not specified, backslashes in the line
6842 are treated as quotations. If a backslash is at the end of the line, it
6843 is treated as a line continuation. When the built-in reads the next
6844 line, the PS2 variable is used as a prompt if the shell is interactive
6845 and the standard input is a terminal.
6846 The input line is subject to field splitting. The resulting words are
6848 assigned to variables in order. If there are more words than variables,
6849 the last variable is assigned all the remaining words (as if the words
6850 were not split). If the words are fewer than variables, the remaining
6851 variables are assigned empty strings.
6852 Options
6854 -A, --array
6855 Make the last variable an array. Instead of assigning a
6856 concatenation of the remaining words to a normal variable, the
6857 words are assigned to an array.
6858 -e, --line-editing
6860 Use line-editing to read the line.
6861 To use line-editing, all of the following conditions must also be
6863 met:
6864 · The shell is interactive.
6866 · The vi or emacs option is enabled.
6868 · The standard input and standard error are connected to a
6870 terminal.
6871 -P, --ps1
6873 Print the PS1 variable as a prompt before reading the (first) line
6874 if the shell is interactive and the standard input is a terminal.
6875 -p prompt, --prompt=prompt
6877 Print the specified prompt before reading the (first) line if the
6878 shell is interactive and the standard input is a terminal.
6879 -r, --raw-mode
6881 Don’t treat backslashes as quotations.
6882 Operands
6884 variables
6885 Names of variables to which input words are assigned.
6886 Exit status
6888 The exit status of the read built-in is zero unless there is any error.
6889 Note that the exit status is non-zero if an end of input is encountered
6891 before reading the entire line.
6892 Notes
6894 The read built-in is a semi-special built-in.
6895 The POSIX standard defines the -r option only: other options cannot be
6897 used in the POSIXly-correct mode.
6898 The PS1R and PS1S variables affect the behavior of line-editing if the
6900 PS1 prompt is used. The same for PS2.
6901
6903 The readonly built-in makes variables and functions read-only.
6904 Syntax
6906 · readonly [-pxX] [name[=value]...]
6907 · readonly -f[p] [name...]
6909 Description
6911 The readonly built-in is equivalent to the typeset built-in with the
6912 -gr option.
6913 Notes
6915 The readonly built-in is a special built-in.
6916 The POSIX standard defines the -p option only; other options cannot be
6918 used in the POSIXly-correct mode. The POSIX does not allow using the
6919 option together with operands.
6920
6922 The return built-in returns from a function or script.
6923 Syntax
6925 · return [-n] [exit_status]
6926 Description
6928 When executed without the -n (--no-return) option, one of the following
6929 happens:
6930 · If the shell is executing a function, the execution of the function
6932 is terminated.
6933 · If the dot built-in is executing a script, the execution of the
6935 script is terminated.
6936 · If the shell is executing a script during initialization, the
6938 execution of the script is terminated.
6939 · If the shell is executing a trap, the execution of the trap is
6941 terminated for the currently handled signal.
6942 · Otherwise, the shell exits unless it is interactive.
6944 When executed with the -n (--no-return) option, the built-in does
6946 nothing but return the specified exit_status.
6947 Options
6949 -n, --no-return
6950 Do not terminate a function, script, trap, or the shell.
6951 Operands
6953 exit_status
6954 The exit status of the built-in.
6955 The value must be a non-negative integer.
6957 If omitted, the exit status of the last executed command is used.
6959 (But when the shell is executing a trap, the exit status of the
6960 last command before the trap is used.)
6961 Exit status
6963 The exit status of the return built-in is defined by the exit_status
6964 operand. The exit status is used also as the exit status of the
6965 terminated function, script, or the shell.
6966 Notes
6968 The return built-in is a special built-in.
6969 The POSIX standard provides that the exit_status operand should be
6971 between 0 and 255 (inclusive). Yash accepts integers larger than 255 as
6972 an extension.
6973 In the POSIX standard, the behavior of the return built-in is defined
6975 only when the shell is executing a function or script.
6976 The POSIX standard defines no options for the return built-in; the
6978 built-in accepts no options in the POSIXly-correct mode.
6979
6981 The set built-in sets shell options and positional parameters.
6982 Syntax
6984 · set [options] [operands]
6985 · set -o
6987 · set +o
6989 The set built-in requires that all options precede operands. Any
6991 command line arguments after the first operand are all treated as
6992 operands.
6993 Description
6995 When executed without any command arguments, the built-in prints a list
6996 of all existing variables to the standard input in a form that can be
6997 reused as commands that will restore the variable definitions.
6998 When -o is the only command argument, the built-in prints a list of
7000 shell options with their current settings. When +o is the only command
7001 argument, the built-in prints commands that can be reused to restore
7002 the current shell option settings.
7003 In other cases, the built-in changes shell option settings and/or
7005 positional parameters.
7006 Options
7008 When one or more options are specified, the built-in enables or
7009 disables the shell options. A normal hyphen-prefixed option enables a
7010 shell option. An option that is prefixed with a plus (+) instead of a
7011 hyphen disables a shell option. For example, options -m, -o monitor,
7012 and --monitor enable the monitor option and options +m, +o monitor,
7013 ++monitor disable it.
7014 The name of a long option is case-insensitive and may include
7016 irrelevant non-alphanumeric characters, which are ignored. For example,
7017 options --le-comp-debug and --LeCompDebug are equivalent. If no is
7018 prepended to the name of a long option, the meaning is reversed. For
7019 example, --noallexport is equivalent to ++allexport and ++nonotify to
7020 --notify.
7021 An option can be specified in one of the following forms:
7023 · a long option e.g. --allexport
7025 · an -o option with a option name specified as the argument e.g. -o
7027 allexport
7028 · a single-character option e.g. -a
7030 Not all options can be specified as single-character options.
7032 The available options are:
7034 all-export (-a)
7036 When enabled, all variables are automatically exported when
7037 assigned.
7038 brace-expand
7040 This option enables brace expansion.
7041 case-glob
7043 (Enabled by default) When enabled, pattern matching is
7044 case-sensitive in pathname expansion.
7045 clobber (+C)
7047 (Enabled by default) When enabled, the > redirection behaves the
7048 same as the >| redirection.
7049 cur-async, cur-bg, cur-stop
7051 (Enabled by default) These options affect choice of the current job
7052 (cf. job ID).
7053 dot-glob
7055 When enabled, periods at the beginning of filenames are not treated
7056 specially in pathname expansion.
7057 emacs
7059 This option enables line-editing in the emacs mode.
7060 empty-last-field
7062 When enabled, field splitting does not remove the last field even
7063 if it is empty.
7064 err-exit (-e)
7066 When enabled, if a pipeline ends with a non-zero exit status, the
7067 shell immediately exits unless the following suppress condition is
7068 met:
7069 · the pipeline is a condition of an if command or while or until
7071 loop;
7072 · the pipeline is prefixed by !; or
7074 · the pipeline is a single compound command other than a subshell
7076 grouping.
7077 err-return
7079 This option is like the err-exit option, but the return built-in is
7080 executed instead of the shell exiting on a non-zero exit status.
7081 Unlike err-exit, the suppress condition does not apply inside a
7082 function, subshell grouping, or script file.
7083 exec (+n)
7085 (Enabled by default) Commands are actually executed only when this
7086 option is enabled. Otherwise, commands are just parsed and not
7087 executed. Disabling this option may be useful for syntax checking.
7088 In an interactive shell, this option is always assumed enabled.
7089 extended-glob
7091 This option enables extension in pathname expansion.
7092 glob (+f)
7094 (Enabled by default) This option enables pathname expansion.
7095 hash-on-def (-h)
7097 When a function is defined when this option is enabled, the shell
7098 immediately performs command path search for each command that
7099 appears in the function and caches the command’s full path.
7100 hist-space
7102 When enabled, command lines that start with a whitespace are not
7103 saved in command history.
7104 ignore-eof
7106 When enabled, an interactive shell does not exit when EOF (end of
7107 file) is input. This prevents the shell from exiting when you
7108 accidentally hit Ctrl-D.
7109 le-always-rp, le-comp-debug, le-conv-meta, le-no-conv-meta, le-predict,
7111 le-predict-empty, le-prompt-sp, le-visible-bell
7112 See shell options on line-editing.
7113 mark-dirs
7115 When enabled, resulting directory names are suffixed by a slash in
7116 pathname expansion.
7117 monitor (-m)
7119 This option enables job control. This option is enabled by default
7120 for an interactive shell.
7121 notify (-b)
7123 When the status of a job changes when this option is enabled, the
7124 shell immediately notifies at any time. This option overrides the
7125 notify-le option.
7126 notify-le
7128 This option is similar to the notify option, but the status change
7129 is notified only while the shell is waiting for input with
7130 line-editing.
7131 null-glob
7133 When enabled, in pathname expansion, patterns that do not match any
7134 pathname are removed from the command line rather than left as is.
7135 pipe-fail
7137 When enabled, the exit status of a pipeline is zero if and only if
7138 all the subcommands of the pipeline exit with an exit status of
7139 zero.
7140 posixly-correct
7142 This option enables the POSIXly-correct mode.
7143 trace-all
7145 (Enabled by default) When this option is disabled, the x-trace
7146 option is temporarily disabled while the shell is executing
7147 commands defined in the COMMAND_NOT_FOUND_HANDLER, PROMPT_COMMAND,
7148 or YASH_AFTER_CD variable.
7149 unset (+u)
7151 (Enabled by default) When enabled, undefined parameters are
7152 expanded to empty strings in parameter expansion. When disabled,
7153 expansion of undefined parameter results in an error.
7154 verbose (-v)
7156 When enabled, the shell prints each command line to the standard
7157 error before parsing and executing it.
7158 vi
7160 This option enables line-editing in the vi mode. This option is
7161 enabled by default in an interactive shell if the standard input
7162 and error are both terminals.
7163 x-trace (-x)
7165 When enabled, the results of expansion are printed to the standard
7166 error for each simple command being executed. When printed, each
7167 line is prepended with an expansion result of the PS4 variable. See
7168 also the trace-all option.
7169 Operands
7171 If one or more operands are passed to the set built-in, current
7172 positional parameters are all removed and the operands are set as new
7173 positional parameters. If the -- separator (cf. syntax of command
7174 arguments) is passed, the positional parameters are set even when there
7175 are no operands, in which case new positional parameters will be
7176 nothing.
7177 Exit status
7179 The exit status of the set built-in is zero unless there is any error.
7180 Notes
7182 The set built-in is a special built-in.
7183 In the POSIX standard, available shell options are much limited. The
7185 standard does not define:
7186 · long options such as --allexport,
7188 · prepending no to negate an option,
7190 · using uppercase letters and/or non-alphanumeric characters in
7192 option names
7193 The options defined in the standard are:
7195 · -a, -o allexport
7197 · -e, -o errexit
7199 · -m, -o monitor
7201 · -C, -o noclobber
7203 · -n, -o noexec
7205 · -f, -o noglob
7207 · -b, -o notify
7209 · -u, -o nounset
7211 · -v, -o verbose
7213 · -x, -o xtrace
7215 · -h
7217 · -o ignoreeof
7219 · -o nolog
7221 · -o vi
7223 Yash does not support the nolog option, which prevents function
7225 definitions from being added to command history.
7226
7228 The shift built-in removes some positional parameters or array values.
7229 Syntax
7231 · shift [-A array] [count]
7232 Description
7234 The shift built-in removes the first count positional parameters or
7235 array values, where count is specified by the operand.
7236 Options
7238 -A array, --array=array
7239 Remove first count values of array instead of positional
7240 parameters.
7241 Operands
7243 count
7244 The number of positional parameters or array values to be removed.
7245 It is an error if the actual number of positional parameters or
7247 array values is less than count. If omitted, the default value is
7248 one. If negative, the last -count positional parameters or array
7249 values are removed instead of the first ones.
7250 Exit status
7252 The exit status of the shift built-in is zero unless there is any
7253 error.
7254 Notes
7256 The shift built-in is a special built-in.
7257 The number of positional parameters can be obtained with the # special
7259 parameter. The number of array values can be obtained with ${array[#]}.
7260 The POSIX standard defines no options for the shift built-in; the
7262 built-in accepts no options in the POSIXly-correct mode.
7263 Negative operands are not allowed in the POSIXly-correct mode.
7265
7267 The suspend built-in suspends the shell.
7268 Syntax
7270 · suspend [-f]
7271 Description
7273 The suspend built-in sends a SIGSTOP signal to all processes in the
7274 process group to which the shell process belongs. The signal suspends
7275 the processes (including the shell). The suspended processes resume
7276 when they receive a SIGCONT signal.
7277 If the shell is interactive and its process group ID is equal to the
7279 process ID of the session leader, the shell prints a warning message
7280 and refuses to send a signal unless the -f (--force) option is
7281 specified. (In such a case, there is no other job-controlling shell
7282 that can send a SIGCONT signal to resume the suspended shell, so the
7283 shell could never be resumed.)
7284 Options
7286 -f, --force
7287 Suppress warnings that would prevent the shell from sending a
7288 signal.
7289 Exit status
7291 The exit status is zero if the signal was successfully sent and
7292 non-zero otherwise.
7293 Notes
7295 The suspend built-in is a semi-special built-in. In the POSIX standard,
7296 it is defined as a command with unspecified behavior.
7297
7299 The test built-in evaluates an expression.
7300 Syntax
7302 · test expression
7303 · [ expression ]
7305 The test built-in does not distinguish options and operands; all
7307 command line arguments are interpreted as expression. If the built-in
7308 is executed with the name [, expression must be followed by ].
7309 Description
7311 The test built-in evaluates expression as a conditional expression that
7312 is made up of operators and operands described below. The exit status
7313 is 0 if the condition is true and 1 otherwise.
7314 The unary operators below test a file. If the operand file is a
7316 symbolic link, the file referred to by the link is tested (except for
7317 the -h and -L operators).
7318 -b file
7320 file is a block special file
7321 -c file
7323 file is a character special file
7324 -d file
7326 file is a directory
7327 -e file
7329 file exists
7330 -f file
7332 file is a regular file
7333 -G file
7335 file's group ID is same as the shell’s effective group ID
7336 -g file
7338 file's set-group-ID flag is set
7339 -h file
7341 same as -L
7342 -k file
7344 file's sticky bit is set
7345 -L file
7347 file is a symbolic link
7348 -N file
7350 file has not been accessed since last modified
7351 -O file
7353 file's user ID is same as the shell’s effective user ID
7354 -p file
7356 file is a FIFO (named pipe)
7357 -r file
7359 file is readable
7360 -S file
7362 file is a socket
7363 -s file
7365 file is not empty
7366 -u file
7368 file's set-user-ID flag is set
7369 -w file
7371 file is writable
7372 -x file
7374 file is executable
7375 The unary operator below tests a file descriptor:
7377 -t fd
7379 fd is associated with a terminal
7380 The unary operators below test a string:
7382 -n string
7384 string is not empty
7385 -z string
7387 string is empty
7388 The unary operator below tests a shell option:
7390 -o ?option
7392 option is a valid shell option name
7393 -o option
7395 option is a valid shell option name that is enabled
7396 The binary operators below compare files. Non-existing files are
7398 considered older than any existing files.
7399 file1 -nt file2
7401 file1 is newer than file2
7402 file1 -ot file2
7404 file1 is older than file2
7405 file1 -ef file2
7407 file1 is a hard link to file2
7408 The binary operators below compare strings:
7410 string1 = string2, string1 == string2
7412 string1 is the same string as string2
7413 string1 != string2
7415 string1 is not the same string as string2
7416 The binary operators below compare strings according to the alphabetic
7418 order in the current locale:
7419 string1 === string2
7421 string1 is equal to string2
7422 string1 !== string2
7424 string1 is not equal to string2
7425 string1 < string2
7427 string1 is less than string2
7428 string1 <= string2
7430 string1 is less than or equal to string2
7431 string1 > string2
7433 string1 is greater than string2
7434 string1 >= string2
7436 string1 is greater than or equal to string2
7437 The binary operator below performs pattern matching:
7439 string =~ pattern
7441 extended regular expression pattern matches (part of) string
7442 The binary operators below compare integers:
7444 v1 -eq v2
7446 v1 is equal to v2
7447 v1 -ne v2
7449 v1 is not equal to v2
7450 v1 -gt v2
7452 v1 is greater than v2
7453 v1 -ge v2
7455 v1 is greater than or equal to v2
7456 v1 -lt v2
7458 v1 is less than v2
7459 v1 -le v2
7461 v1 is less than or equal to v2
7462 The binary operators below compare version numbers:
7464 v1 -veq v2
7466 v1 is equal to v2
7467 v1 -vne v2
7469 v1 is not equal to v2
7470 v1 -vgt v2
7472 v1 is greater than v2
7473 v1 -vge v2
7475 v1 is greater than or equal to v2
7476 v1 -vlt v2
7478 v1 is less than v2
7479 v1 -vle v2
7481 v1 is less than or equal to v2
7482 The operators below can be used to make complex expressions:
7484 ! expression
7486 negate (reverse) the result
7487 ( expression )
7489 change operator precedence
7490 expression1 -a expression2
7492 logical conjunction (and)
7493 expression1 -o expression2
7495 logical disjunction (or)
7496 If the expression is a single word without operators, the -n operator
7498 is assumed. An empty expression evaluates to false.
7499 Comparison of version numbers
7501 Comparison of version numbers is similar to comparison of strings
7502 in alphabetic order. The differences are:
7503 · Adjacent digits are treated as an integer. Integers are
7505 compared in mathematical order rather than alphabetic order.
7506 · Digits are considered larger than any non-digit characters.
7508 For example, version numbers 0.1.2-3 and 00.001.02-3 are equal and
7510 0.2.1 is smaller than 0.10.0.
7511 Exit status
7513 The exit status of the test built-in is 0 if expression is true and 1
7514 otherwise. The exit status is 2 if expression cannot be evaluated
7515 because of a syntax error or any other reasons.
7516 Notes
7518 Complex expressions may cause confusion and should be avoided. Use the
7519 shell’s compound commands. For example, [ 1 -eq 1 ] && [ -t = 1 ] && !
7520 [ foo ] is preferred over [ 1 -eq 1 -a -t = 1 -a ! foo ].
7521 The POSIX standard provides that the exit status should be larger than
7523 1 on error. The POSIX standard does not define the following operators:
7524 -G, -k, -N, -O, -nt, -ot, -ef, ==, ===, !==, <, <=, >, >=, =~, -veq,
7525 -vne, -vgt, -vge, -vlt, and -vle. POSIX neither specifies -o as a unary
7526 operator.
7527
7529 The times built-in prints CPU time usage.
7530 Syntax
7532 · times
7533 Description
7535 The times built-in prints the CPU times consumed by the shell process
7536 and its child processes to the standard output.
7537 The built-in prints two lines: the first line shows the CPU time of the
7539 shell process and the second one that of its child processes (not
7540 including those which have not terminated). Each line shows the CPU
7541 times consumed in the user and system mode.
7542 Exit status
7544 The exit status of the times built-in is zero unless there is any
7545 error.
7546 Notes
7548 The times built-in is a special built-in.
7549
7551 The trap built-in sets or prints signal handlers.
7552 Syntax
7554 · trap
7555 · trap action signal...
7557 · trap signal_number [signal...]
7559 · trap -p [signal...]
7561 Description
7563 The trap built-in sets or prints actions that are taken when the shell
7564 receives signals. (Those actions are called traps.)
7565 When executed with action and one or more signals, the built-in sets
7567 the traps for signals to action. If the shell receives one of the
7568 signals, the action will be taken.
7569 If the first operand is signal_number instead of action, the built-in
7571 resets the traps for signal_number and signals as if action was -.
7572 When executed with the -p (--print) option or with no operands, the
7574 built-in prints currently set traps to the standard output in a format
7575 that can be executed as commands that restore the current traps. If one
7576 or more signals are specified, only those signals are printed.
7577 Otherwise, all signals with non-default actions are printed. (In some
7578 situations, however, the built-in may print previous trap settings
7579 instead of the current. See notes below.)
7580 Options
7582 -p, --print
7583 Print current trap settings.
7584 Operands
7586 action
7587 An action that will be taken when signal is received.
7588 If action is a single hyphen (-), the action is reset to the
7590 default action that is defined by the operating system. If action
7591 is an empty string, the signal is ignored on receipt. Otherwise,
7592 action is treated as a command string: the string is parsed and
7593 executed as commands when the signal is received. (If a signal is
7594 received while a command is being executed, the action is taken
7595 just after the command finishes.)
7596 signal
7598 The number or name of a signal.
7599 If signal is number 0 or name EXIT, it is treated as a special
7601 imaginary signal that is always received when the shell exits. The
7602 action set for this signal is taken when the shell exits normally.
7603 signal_number
7605 This is like signal, but must be a number.
7606 Exit status
7608 The exit status of the trap built-in is zero unless there is any error.
7609 Notes
7611 The trap built-in is a special built-in.
7612 The POSIX standard defines no options for the trap built-in; the
7614 built-in accepts no options in the POSIXly-correct mode.
7615 The POSIX standard requires that signal names must be specified without
7617 the SIG-prefix, like INT and QUIT. As an extension, yash accepts
7618 SIG-prefixed names like SIGINT and SIGQUIT and treats signal names
7619 case-insensitively.
7620 Reusing output of the built-in
7622 Output of the trap built-in can be saved in a variable, which can
7623 be later executed by the eval built-in to restore the traps.
7624 saved_traps=$(trap)
7626 trap '...' INT
7627 eval "$saved_traps"
7628 There are some tricks behind the scenes to allow this idiom. You
7630 use a command substitution to save the output of the trap built-in
7631 in the variable. The command substitution is executed in a
7632 subshell. The subshell resets all traps (except ignored ones) at
7633 the beginning of itself. This seemingly would result in (almost)
7634 empty output from the built-in that would fail to restore the traps
7635 as expected.
7636 To avoid that pitfall, POSIX requires the shell to follow one of
7638 the two options below:
7639 · If a command substitution just contains a single trap built-in,
7641 traps should not be reset when the subshell is started to
7642 execute the built-in; or
7643 · A subshell always resets the traps but remembers the previous
7645 traps. If the trap built-in is executed in the subshell but no
7646 other trap built-in has been executed to modify traps in the
7647 subshell, then the built-in should print the remembered traps.
7648 Yash obeys the second.
7650
7652 The true built-in does nothing successfully.
7653 Syntax
7655 · true
7656 Description
7658 The true built-in does nothing. Any command line arguments are ignored.
7659 Exit status
7661 The exit status of the true built-in is zero.
7662 Notes
7664 The true built-in is a semi-special built-in.
7665 The true and colon built-ins have the same effect, but true is a
7667 semi-special built-in while colon is a special.
7668
7670 The type built-in identifies a command.
7671 Syntax
7673 · type [-abefkp] [command...]
7674 Description
7676 The type built-in is equivalent to the command built-in with the -V
7677 option.
7678 Notes
7680 The POSIX standard does not define the relation between the type and
7681 command built-ins. The standard does not define options for the type
7682 built-in.
7683 At least one command operand must be specified in the POSIXly-correct
7685 mode.
7686 The type built-in is a semi-special built-in.
7688
7690 The typeset built-in prints or sets variables or functions.
7691 Syntax
7693 · typeset [-gprxX] [variable[=value]...]
7694 · typeset -f[pr] [function...]
7696 Description
7698 If executed without the -f (--functions) option, the typeset built-in
7699 prints or sets variables to the standard output. Otherwise, it prints
7700 or sets functions.
7701 If executed with the -p (--print) option, the built-in prints the
7703 variables or functions specified by operands. Without the option, it
7704 sets variables or functions. If no operands are specified, it prints
7705 all existing variables or functions, regardless of whether the -p
7706 (--print) option is specified.
7707 Options
7709 -f, --functions
7710 Print or set functions rather than variables.
7711 -g, --global
7713 When setting a new variable, the variable will be a global variable
7714 if this option is specified. Without this option, the variable
7715 would be a local variable.
7716 When printing variables, all existing variables including global
7718 variables are printed if this option is specified. Without this
7719 option, only local variables are printed.
7720 -p, --print
7722 Print variables or functions in a form that can be parsed and
7723 executed as commands that will restore the currently set variables
7724 or functions.
7725 -r, --readonly
7727 When setting variables or functions, make them read-only.
7728 When printing variables or functions, print read-only variables or
7730 functions only.
7731 -x, --export
7733 When setting variables, mark them for export, so that they will be
7734 exported to external commands.
7735 When printing variables, print exported variables only.
7737 -X, --unexport
7739 When setting variables, cancel exportation of the variables.
7740 Operands
7742 variable (without value)
7743 The name of a variable that is to be set or printed.
7744 Without the -p (--print) option, the variable is defined (if not
7746 yet defined) but its value is not set nor changed. Variables that
7747 are defined without values are treated as unset in parameter
7748 expansion.
7749 variable=value
7751 The name of a variable and its new value.
7752 The value is assigned to the variable (regardless of the -p
7754 (--print) option).
7755 function
7757 The name of an existing function that is to be set or printed.
7758 Exit status
7760 The exit status of the typeset built-in is zero unless there is any
7761 error.
7762 Notes
7764 A global variable cannot be newly defined if a local variable has
7765 already been defined with the same name. The local variable will be set
7766 regardless of the -g (--global) option.
7767 The typeset built-in is a semi-special built-in. In the POSIX standard,
7769 it is defined as a command with unspecified behavior.
7770 The export and readonly built-ins are equivalent to the typeset
7772 built-in with the -gx and -gr options, respectively. The local built-in
7773 is equivalent to the typeset built-in except that the -f (--functions)
7774 and -g (--global) options cannot be used.
7775
7777 The ulimit built-in sets or prints a resource limit.
7778 Syntax
7780 · ulimit -a [-H|-S]
7781 · ulimit [-H|-S] [-efilnqrstuvx] [limit]
7783 Description
7785 The ulimit built-in sets or prints a resource limit.
7786 If executed with the -a (--all) option, the built-in prints the current
7788 limits for all resource types. Otherwise, it sets or prints the limit
7789 of a single resource type. The resource type can be specified by the
7790 options listed below. The resource limits will affect the current shell
7791 process and all commands invoked from the shell.
7792 Each resource type has two limit values: the hard and soft limit. You
7794 can change a soft limit freely as long as it does not exceed the hard
7795 limit. You can decrease a hard limit but cannot increase it without a
7796 proper permission.
7797 When the -H (--hard) or -S (--soft) option is specified, the built-in
7799 sets or prints the hard or soft limit, respectively. If neither of the
7800 options is specified, the built-in sets both the hard and soft limit or
7801 prints the soft limit.
7802 Options
7804 -H, --hard
7805 Set or print a hard limit.
7806 -S, --soft
7808 Set or print a soft limit.
7809 -a, --all
7811 Print all current limit settings.
7812 The following options specify the type of resources. If none of them is
7814 specified, -f is the default. The types of resources that can be set
7815 depend on the operating system.
7816 -c, --core
7818 Maximum size of core files created (in 512-byte blocks)
7819 -d, --data
7821 Maximum size of a process’s data segment (in kilobytes)
7822 -e, --nice
7824 Maximum scheduling priority (‘nice’)
7825 -f, --fsize
7827 Maximum size of files created by a process (in 512-byte blocks)
7828 -i, --sigpending
7830 Maximum number of pending signals
7831 -l, --memlock
7833 Maximum memory size that can be locked into RAM (in kilobytes)
7834 -m, --rss
7836 Maximum size of a process’s resident set (in kilobytes)
7837 -n, --nofile
7839 Maximum file descriptor + 1
7840 -q, --msgqueue
7842 Maximum size of POSIX message queues
7843 -r, --rtprio
7845 Maximum real-time scheduling priority
7846 -s, --stack
7848 Maximum size of a process’s stack (in kilobytes)
7849 -t, --cpu
7851 Maximum CPU time that can be used by a process (in seconds)
7852 -u, --nproc
7854 Maximum number of processes for a user
7855 -v, --as
7857 Maximum size of memory used by a process (in kilobytes)
7858 -x, --locks
7860 Maximum number of file locks
7861 Operands
7863 limit
7864 A limit to be set.
7865 The value must be a non-negative integer or one of hard, soft, and
7867 unlimited. If value is hard or soft, the new limit is set to the
7868 current hard or soft limit. If limit is not specified, the current
7869 limit is printed.
7870 Exit status
7872 The exit status of the ulimit built-in is zero unless there is any
7873 error.
7874 Notes
7876 The POSIX standard defines no options other than -f. It neither defines
7877 hard, soft, or unlimited for limit values.
7878 The ulimit built-in is a semi-special built-in.
7880
7882 The umask built-in sets or prints the file mode creation mask.
7883 Syntax
7885 · umask mask
7886 · umask [-S]
7888 Description
7890 If executed without the mask operand, the built-in prints the current
7891 file mode creation mask of the shell to the standard output in a form
7892 that can later be used as mask to restore the current mask.
7893 Otherwise, the built-in sets the file mode creation mask to mask.
7895 Options
7897 -S, --symbolic
7898 Print in the symbolic form instead of the octal integer form.
7899 Operands
7901 mask
7902 The new file mode creation mask either in the symbolic or octal
7903 integer form.
7904 Octal integer form
7906 In the octal integer form, the mask is specified as a non-negative
7907 octal integer that is the sum of the following permissions:
7908 0400
7910 read by owner
7911 0200
7913 write by owner
7914 0100
7916 execute/search by owner
7917 0040
7919 read by group
7920 0020
7922 write by group
7923 0010
7925 execute/search by group
7926 0004
7928 read by others
7929 0002
7931 write by others
7932 0001
7934 execute/search by others
7935 Symbolic form
7937 In the symbolic form, the mask is specified as a symbolic
7938 expression that denotes permissions that are not included in the
7939 mask.
7940 The entire expression is one or more clauses separated by comma. A
7942 clause is a sequence of whos followed by one or more actions.
7943 A who is one of:
7945 u
7947 owner
7948 g
7950 group
7951 o
7953 others
7954 a
7956 all of owner, group, and others
7957 An empty sequence of whos is equivalent to who a.
7959 An action is an operator followed by permission. An operator is one
7961 of:
7962 =
7964 set who's permission to permission
7965 +
7967 add permission to who's permission
7968 -
7970 remove permission from who's permission
7971 and permission is one of:
7973 r
7975 read
7976 w
7978 write
7979 x
7981 execute/search
7982 X
7984 execute/search (only if some user already has execute/search
7985 permission)
7986 s
7988 set-user-ID and set-group-ID
7989 u
7991 user’s current permissions
7992 g
7994 group’s current permissions
7995 o
7997 others' current permissions
7998 but more than one of r, w, x, X, and s can be specified after a
8000 single operand.
8001 For example, the command umask u=rwx,go+r-w
8003 · unmasks the user’s read, write, and execute/search permissions;
8005 · unmasks the group’s and others' read permission; and
8007 · masks the group’s and others' write permission.
8009 Exit status
8011 The exit status of the umask built-in is zero unless there is any
8012 error.
8013 Notes
8015 The umask built-in is a semi-special built-in.
8016 The POSIX standard does not require the default output format (used
8018 when the -S option is not specified) to be the octal integer form.
8019
8021 The unalias built-in undefines aliases.
8022 Syntax
8024 · unalias name...
8025 · unalias -a
8027 Description
8029 The unalias built-in removes the definition of the aliases specified by
8030 operands.
8031 Options
8033 -a, --all
8034 Undefine all aliases.
8035 Operands
8037 name
8038 The name of an alias to be undefined.
8039 Exit status
8041 The exit status of the unalias built-in is zero unless there is any
8042 error. It is an error to specify the name of a non-existing alias as
8043 name.
8044 Notes
8046 The unalias built-in is a semi-special built-in.
8047
8049 The unset built-in undefines variables or functions.
8050 Syntax
8052 · unset [-fv] [name...]
8053 Description
8055 The unset built-in removes the definition of the variables or functions
8056 specified by operands.
8057 It is not an error if any of the specified variables or functions do
8059 not exist; they are silently ignored.
8060 Options
8062 -f, --functions
8063 Undefine functions.
8064 -v, --variables
8066 Undefine variables.
8067 These options are mutually exclusive: only the last specified one is
8069 effective. If neither is specified, -v is assumed.
8070 Operands
8072 name
8073 The name of a variable or function to be undefined.
8074 Exit status
8076 The exit status of the unset built-in is zero unless there is any
8077 error.
8078 Notes
8080 The unset built-in is a special built-in.
8081 Although yash does not do so, the POSIX standard allows removing a
8083 function if neither of the -f and -v options is specified and the
8084 specified variable does not exist.
8085 At least one name operand must be specified in the POSIXly-correct
8087 mode.
8088
8090 The wait built-in waits for jobs to terminate.
8091 Syntax
8093 · wait [job...]
8094 Description
8096 The wait built-in waits for background jobs to terminate. If job
8097 control is enabled, stopped jobs are considered as terminated.
8098 The built-in can be used to wait for asynchronous commands if job
8100 control is disabled.
8101 If the shell receives a signal while the built-in is waiting and if a
8103 trap has been set for the signal, then the trap is executed and the
8104 built-in immediately finishes (without waiting for the jobs). If the
8105 shell receives a SIGINT signal when job control is enabled, the
8106 built-in aborts waiting.
8107 If the shell is interactive, job-controlling, and not in the
8109 POSIXly-correct mode, the job status is printed when the job is
8110 terminated or stopped.
8111 Operands
8113 job
8114 The job ID of the job or the process ID of a process in the job.
8115 If no jobs are specified, the built-in waits for all existing jobs.
8117 If the specified job does not exist, the job is considered to have
8119 terminated with the exit status of 127.
8120 Exit status
8122 If no jobs were specified and the built-in successfully waited for all
8123 the jobs, the exit status is zero. If one or more jobs were specified,
8124 the exit status is that of the last job.
8125 If the built-in was aborted by a signal, the exit status is an integer
8127 (> 128) that denotes the signal. If there was any other error, the exit
8128 status is between 1 and 126 (inclusive).
8129 Notes
8131 The wait built-in is a semi-special built-in.
8132 The process ID of the last process of a job can be obtained by the !
8134 special parameter. You can use the jobs built-in as well to obtain
8135 process IDs of job processes.
8136
8138 Yuki Watanabe <magicant@users.osdn.me>
8139 Author.
8140 2.48 2018-12-22 YASH(1)