Command line arguments¶

The syntax of command line arguments for yash conforms to POSIX. As defined in POSIX, arguments are separated into options and operands. For more detailed explanation about options and operands, see Command argument syntax. All options must come before operands. The interpretation of operands depends on options specified.

When you specify the -c (--cmdline) option, you must give at least one operand. The shell interprets and executes the first operand as a command string. The second operand, if any, is used to initialize the 0 special parameter. The other operands, if any, are used to initialize the positional parameters. When the -c (--cmdline) option is specified, the shell does not read any file or the standard input (unless the dot built-in is used).

If you specify the -s (--stdin) option, the shell reads the standard input, interprets the input as commands, and executes them. All the operands given are used to initialize the positional parameters. The 0 special parameter is initialized to the name the shell is invoked as.

If you specify neither the -c (--cmdline) nor -s (--stdin) option, the shell reads a file, interprets the file contents as commands, and executes them. The first operand specifies the pathname of the file. The remaining operands are used to initialize the positional parameters. If you do not give any operands, the shell reads the standard input as if the -s (--stdin) option is specified.

You cannot use both the -c (--cmdline) and -s (--stdin) options at a time.

If you specify either the --help or -V (--version) option, the shell never performs the usual initialization or command execution. Instead, it just prints brief usage (for --help) or version information (for -V and --version). If the -V (--version) option is accompanied by the -v (--verbose) option, the shell prints a list of the available optional features as well.

If you specify the -i (--interactive) option, the shell goes into the interactive mode. If you specify the +i (++interactive) option, conversely, the shell never goes into the interactive mode.

If you specify the -l (--login) option, the shell behaves as a login shell.

The --noprofile, --norcfile, --profile, and --rcfile options determine how the shell is initialized (see below for details).

In addition to the options described above, you can specify options that can be specified to the set built-in.

If the first operand is - and the options and the operands are not separated by --, the first operand is ignored.

Initialization of yash¶

Yash initializes itself as follows:

Tokens and keywords¶

A command is composed of one or more tokens. In the shell syntax, a token is a word that is part of a command. Normally, tokens are separated by whitespaces, that is, the space or tab character. Whitespaces inside a command substitution or a parameter expansion, however, do not separate tokens.

The following symbols have special meanings in the shell syntax and in most cases separate tokens:

; & | < > ( ) [newline]

The following symbols do not separate tokens, but have syntactic meanings:

$ ` \ " ' * ? [ # ~ = %

The following tokens are treated as keywords depending on the context in which they appear:

! { } [[ case do done elif else esac fi
for function if in then until while

A token is treated as a keyword when:

If a token begins with #, then the # and any following characters up to the end of the line are treated as a comment, which is completely ignored in syntax parsing.

Quotations¶

If you want whitespaces, separator characters, or keywords described above to be treated as a normal characters, you must quote the characters using appropriate quotation marks. Quotation marks are not treated as normal characters unless they are themselves quoted. You can use the following three quotation marks:

Aliases¶

Tokens that compose a command are subject to alias substitution. A token that matches the name of an alias that has already been defined is substituted with the value of the alias before the command is parsed.

Tokens that contain quotations are not alias-substituted since an alias name cannot contain quotation marks. Keywords and command separator characters are not alias-substituted either.

There are two kinds of aliases: normal aliases and global aliases. A normal alias can only substitute the first token of a command while a global alias can substitute any part of a command. Global aliases are yash extension that is not defined in POSIX.

If a token is alias-substituted with the value of a normal alias that ends with a whitespace, the next token is exceptionally subject to alias substitution for normal aliases.

The results of alias substitution are again subject to alias substitution for other aliases (but not for the aliases that have been already applied).

You can define aliases using the alias built-in and remove using the unalias built-in.

Simple commands¶

A command that does not start with a keyword token is a simple command. Simple commands are executed as defined in Execution of simple commands.

If the first and any number of following tokens of a simple command have the form name=value, they are interpreted as variable assignments. A variable name must consist of one or more alphabets, digits and/or underlines (_) and must not start with a digit. The first token that is not a variable assignment is considered as a command name and all the following tokens (whether or not they have the form name=value) as command arguments.

A variable assignment of the form var=(tokens) is interpreted as assignment to an array. You can write any number of tokens between a pair of parentheses. Tokens can be separated by not only spaces and tabs but also newlines.

Pipelines¶

A pipeline is a sequence of one or more simple commands, compound commands, and/or function definitions that are separated by |.

A pipeline that has more than one subcommand is executed by executing each subcommand of the pipeline in a subshell simultaneously. The standard output of each subcommand except the last one is redirected to the standard input of the next subcommand. The standard input of the first subcommand and the standard output of the last subcommand are not redirected.

The exit status of the pipeline is that of the last subcommand unless the pipe-fail option is enabled, in which case the exit status of the pipeline is that of the last subcommand that exits with a non-zero exit status. If all the subcommands exit with an exit status of zero, the exit status of the pipeline is also zero.

A pipeline can be prefixed by !, in which case the exit status of the pipeline is reversed: the exit status of the pipeline is 1 if that of the last subcommand is 0, and 0 otherwise.

Korn shell treats a word of the form !(...) as an extended pathname expansion pattern that is not defined in POSIX. In the POSIXly-correct mode, the tokens ! and ( must be separated by one or more white spaces.

And/or lists¶

An and/or list is a sequence of one or more pipelines separated by && or ||.

An and/or list is executed by executing some of the pipelines conditionally. The first pipeline is always executed. The other pipelines are either executed or not executed according to the exit status of the previous pipelines.

The exit status of an and/or list is that of the last pipeline that was executed.

Normally, an and/or list must be terminated by a semicolon, ampersand, or newline. See Command separators and asynchronous commands.

Command separators and asynchronous commands¶

The whole input to the shell must be composed of any number of and/or lists separated by a semicolon or ampersand. A terminating semicolon can be omitted if it is followed by ;;, ), or a newline. Otherwise, an and/or list must be terminated by a semicolon or ampersand.

If an and/or list is terminated by a semicolon, it is executed synchronously: the shell waits for the and/or list to finish before executing the next and/or list. If an and/or list is terminated by an ampersand, it is executed asynchronously: after the execution of the and/or list is started, the next and/or list is executed immediately. An asynchronous and/or list is always executed in a subshell and its exit status is zero.

If the shell is not doing job control, the standard input of an asynchronous and/or list is automatically redirected to /dev/null. Signal handlers of the and/or list for the SIGINT and SIGQUIT signals are set to “ignore” the signal so that the execution of the and/or list cannot be stopped by those signals.

When the execution of an asynchronous and/or list is started, the shell remembers its process ID. You can obtain the ID by referencing the ! special parameter. You can obtain the current and exit status of the asynchronous list as well by using the jobs and wait built-ins.

Compound commands¶

Compound commands provide you with programmatic control of shell command execution.

Grouping

If command

While and until loops

For loop

Case command

Double-bracket command

Function definition¶

The function definition command defines a function.

Function definition syntax

In the first syntax without the function keyword, funcname cannot contain any special characters such as semicolons and quotation marks. In the second and third syntax, which cannot be used in the POSIXly-correct mode, funcname is subjected to the four expansions when executed. In the POSIXly-correct mode, funcname is limited to a portable (ASCII-only) name.

When a function definition command is executed, a function whose name is funcname is defined with its body being compound_command.

A function definition command cannot be directly redirected. Any redirections that follow a function definition are associated with compound_command rather than the whole function definition command. In func() { cat; } >/dev/null, for example, it is not func() { cat; } but { cat; } that is redirected.

The exit status of a function definition is zero if the function was defined without errors, and non-zero otherwise.

Positional parameters¶

Positional parameters are parameters that are identified by natural numbers. If there are three positional parameters, for example, they are identified as 1, 2, and 3. You can obtain the number of positional parameters by the # special parameter. The * and @ special parameters are expanded to all positional parameters.

Positional parameters are initialized from the shell’s command line arguments when the shell is started (see Command line arguments). In the initialization, the order of the operands are preserved as the order of the positional parameters.

When the shell executes a function call, positional parameters are changed to the arguments to the function call so that you can access the arguments while the function is being executed. Positional parameters are restored to the original values when the execution of the function is finished.

Positional parameters can be manipulated by built-in commands like set and shift.

Note that 0 is not a positional parameter but a special parameter.

Special parameters¶

Special parameters are parameters each identified by a single symbol. They cannot be directly assigned to by the user.

Yash provides the following special parameters:

0

#

$

-

?

!

*

@

Variables¶

Variables are parameters the user can assign values to. Each variable has a name that identifies it and a value that defines the results of expansion.

A variable name is composed of one or more alphanumeric characters and underscores (_). A name cannot start with a digit. Other characters may be used in a name depending on internationalization support of your environment.

Variables that are exported to external commands are called environment variables. They are passed to all external commands the shell invokes. Variables passed to the shell in invocation will be automatically exported.

You can assign to variables by a simple command as well as the typeset built-in. You can remove variables by using the unset built-in.

Variables used by the shell

Arrays

Tilde expansion¶

In tilde expansion, parts of words that start with a tilde (~) are substituted with particular pathnames. The part of each word that gets substituted is from the beginning of the word, which is a tilde, up to (but not including) the first slash (/) in the word. If the word does not contain a slash, the whole word is substituted. If any character in the substituted part is quoted, tilde expansion is not performed on the word.

The results of expansion are determined by the format of the substituted part:

~

~username

~+

~-

~+n, ~-n

When tilde expansion is performed on the value of a variable assignment that occurs during execution of a simple command, the value is considered as a colon-separated list of words and those words are each subject to tilde expansion. For example, the variable assignment

VAR=~/a:~/b:~/c

is equivalent to

VAR=/home/foo/a:/home/foo/b:/home/foo/c

if the value of HOME variable is /home/foo.

The POSIX standard does not prescribe how the shell should behave when it encounters an error during tilde expansion (e.g., when the HOME variable is not defined). Yash silently ignores any errors during tilde expansion; the part of the word that would be substituted is left intact.

In the POSIXly-correct mode, tilde expansion supports the formats of ~ and ~username only.

Parameter expansion¶

Parameter expansion expands to the value of a parameter.

The syntax of typical, simple parameter expansion is ${parameter}, which expands to the value of the parameter whose name is parameter. You can omit the braces (e.g., $parameter) if

If parameter is none of a special parameter, positional parameter, and variable, it is a syntax error. (Some shells other than yash may treat such a case as an expansion error.)

If the unset option is disabled and the parameter is an undefined variable, it is an expansion error. If the unset option is enabled, an undefined variable expands to the empty string.

More complex syntax of parameter expansion allows modifying the value of a parameter.

Parameter expansion

The spaces in the syntax definition above are for readability only and must be omitted. You can omit prefix, index, and/or modifier.

Prefix

Parameter name

Index

where word1 and word2 are parsed in the same manner as normal tokens except that they are always delimited by , or ] and can contain whitespace characters.

If there is an index in a parameter expansion, it is interpreted as follows:

If parameter is an array variable, the index specifies the part of the array. If parameter is either the * or @ special parameter, the index specifies the index range of positional parameters. In other cases, the index specifies the index range of a substring of the parameter value that is being expanded. In all cases, the specified range of the array values, positional parameters, or parameter value remains in the results of the expansion and other values are dropped.

If the interpretation of index is one or two integers, the following rules apply:

If the interpretation of index is one of *, @, and #, it is treated as follows:

*

@

#

If a parameter expansion does not contain an index, it is assumed to be [@]. In the POSIXly-correct mode, index cannot be specified.

Example 1. Expansion of a normal variable

The following commands will print the string ABC:

var='123ABC789'
echo "${var[4,6]}"

Example 2. Expansion of positional parameters

The following commands will print the string 2 3 4:

set 1 2 3 4 5
echo "${*[2,-2]}"

Example 3. Expansion of an array

The following commands will print the string 2 3 4:

array=(1 2 3 4 5)
echo "${array[2,-2]}"

Modifier

Command substitution¶

Command substitution expands to output of commands specified.

Command substitution

When command substitution is evaluated, commands are executed by a subshell with output pipelined to the shell. When the commands finished, command substitution is substituted with the output of the commands. Any trailing newline characters in the output are ignored.

When command substitution of the form $(commands) is parsed, the commands are parsed carefully so that complex commands such as nested command substitution are parsed correctly. If commands start with (, you should put a space before commands so that the whole command substitution is not confused with arithmetic expansion. If the shell is in the POSIXly-correctly mode, the commands are parsed each time the command substitution is expanded; otherwise, commands are parsed only when the command substitution is parsed.

If command substitution is of the form `commands`, the commands are not parsed when the command substitution is parsed; the commands are parsed each time the command substitution is expanded. The end of commands is detected by the first backquote character (`) after the beginning of commands that is not quoted by a backslash. Backquotes that are part of commands (typically used for nested command substitution) must be quoted by backslashes. In commands, backslashes are treated as quotes only when preceding a dollar ($), backquote, newline, or another backslash. Additionally, if the command substitution occurs inside double quotes, double quotes in commands must be quoted with a backslash. Those backslashes are removed before commands are parsed.

Arithmetic expansion¶

Arithmetic expansion evaluates an arithmetic expression and expands to the value of the expression.

Arithmetic expansion

When arithmetic expansion is expanded, the expression is subject to parameter expansion, command substitution, and (nested) arithmetic expansion. The expression is parsed in (almost) same manner as an expression of the C programming language.

Yash allows an expression to be either an integer (of the long type in C) or a floating-point number (of the double type in C). An operation on integers yields an integer and an operation involving a floating-point number yields a floating-point number. In the POSIXly-correct mode, you can use integers only.

The following operators are available (in the order of precedence):

The ++ and -- operators cannot be used in the POSIXly-correct mode.

An atomic expression can be one of an integer literal, a floating-point number literal, and a variable. Literals are parsed in the same manner as in C. An octal integer literal starts with 0, and hexadecimal with 0x. A floating-point number literal may have an exponent (i.e. 1.23e+6). A variable with a non-numeric value will result in an error when parsed as a number. An unset variable is treated as a value of zero if the unset option is enabled.

In the POSIXly-correct mode, variables are always parsed as numbers. Otherwise, variables are parsed only when they are used as numbers in computation. Unparsed variables are left intact.

set +o posixly-correct
foo=bar
echo $((0 ? foo : foo)) # prints "bar"
echo $((foo + 0))       # error

It is an expansion error if the result of an expression is not defined in C.

Brace expansion¶

Brace expansion expands to several split words with preceding and succeeding portions duplicated to each split words. Brace expansion is expanded only when the brace-expand option is enabled.

Comma-separated brace expansion

Range brace expansion

Comma-separated brace expansion is expanded to each comma-separated word. For example, a{1,2,3}b is expanded to the three words a1b, a2b, and a3b.

Range brace expansion is expanded to integers in the range defined by start and end. The difference between each integer can be defined by delta. If start is larger than end, the results will be in descending order. When ..delta is omitted, it defaults to 1 or -1. For example, a{1..3}b is expanded to the three words a1b, a2b, and a3b; and a{1..7..2}b to the four words a1b, a3b, a5b, and a7b.

Multiple brace expansions can be used in one word. Brace expansions can also be nested. You can quote braces and/or commas to prevent them from being treated as brace expansion.

Any errors in brace expansion are silently ignored.

Field splitting¶

In field splitting, words are split at predefined separators.

Field splitting can occur only within parts of words that resulted from parameter expansion, command substitution, and arithmetic expansion that are not between double-quotation marks. Expansion results of the @ special parameter are exceptionally split even between double-quotation marks.

Separators used in field splitting are defined by the value of the IFS variable. If the variable does not exist, the value is assumed to be the three characters of space, tab, and newline.

Characters included in the value of the IFS variable are called IFS characters. IFS characters that are any of space, tab, and newline are called IFS whitespace and other IFS characters are called IFS non-whitespace.

Field splitting is performed as follows:

Finally, the last word is removed from the results if:

Pathname expansion¶

Pathname expansion performs pattern matching and expands to pathnames matched by the pattern.

A word subjected to pathname expansion is treated as a pattern. If one or more pathnames are found that are matched by the pattern, the pathnames become the results of the pathname expansion.

Pathname expansion is not performed when the glob option is disabled.

The shell searches readable directories for matching pathnames. Unreadable directories are silently ignored.

The following options affect the behavior of pathname expansion:

null-glob

case-glob

dot-glob

mark-dirs

extended-glob

Any errors in pathname expansion are silently ignored. If the word is an invalid pattern, it just becomes the result. The results depend on the null-glob option when no matching pathnames are found.

Pattern matching is done for each filename (or pathname component) of pathnames. The shell skips matching for literal patterns that contain no wildcards or bracket expressions. As a result, the patterns /*/foo and /*/fo[o] may yield different expansion results when the case-glob option is disabled; for example, the pattern /*/fo[o] matches the pathname /bar/FOO but the pattern /*/foo does not because matching is skipped for foo.

Extension in pathname expansion

Normal characters¶

A character that is not quoted or any of special characters defined below is a normal character, which matches the character itself.

For example, the pattern abc matches the string abc, and not any other strings.

Single-character wildcard¶

The character ? matches any single character.

For example, the pattern a?c matches any three-character strings that starts with a and ends with c, such as aac, abc, and a;c.

Multi-character wildcard¶

The character * matches any strings (of any length, including the empty string).

For example, the pattern a*c matches any string that starts with a and ends with c, such as ac, abc, and a;xyz;c.

Bracket expression¶

A pattern that is enclosed by brackets ([ and ]) is a bracket expression. A bracket expression must have at least one character between the brackets. The characters between the brackets are interpreted as a bracket expression pattern, which is a below-defined special notation for bracket expression. A bracket expression pattern represents a set of characters. The bracket expression matches any one of the characters in the set the bracket expression pattern represents.

If the opening bracket ([) is followed by an exclamation mark (!), the exclamation is not treated as part of the bracket expression pattern and the whole bracket expression instead matches a character that is not included in the set the bracket expression pattern represents. If the opening bracket is followed by a caret (^), it is treated like an exclamation mark as above (but shells other than yash may treat the caret differently).

If the opening bracket (or the following exclamation or caret, if any) is followed by a closing bracket (]), it is treated as part of the bracket expression pattern rather than the end of the bracket expression. You cannot quote characters in the bracket expression pattern because quotation is treated before bracket expression.

An opening bracket in a pattern is treated as a normal character if it is not the beginning of a valid bracket expression.

Normal characters (in bracket expression pattern)¶

A character that is not any of special characters defined below is a normal character, which represents the character itself.

For example, the bracket expression pattern abc represents the set of the three characters a, b, and c. The bracket expression [abc] therefore matches any of the three characters.

Range expressions¶

A hyphen preceded and followed by a character (or collating symbol) is a range expression, which represents the set of the two characters and all characters between the two in the collation order. A collation order is an order of characters that is defined in the locale data.

If a hyphen is followed by a closing bracket (]), the bracket is treated as the end of the bracket expression and the hyphen as a normal character.

For example, the range expression 3-5 represents the set of the three characters 3, 4, and 5. The bracket expression [3-5-] therefore matches one of the four characters 3, 4, 5, and -.

Collating symbols¶

A collating symbol allows more than one character to be treated as a single character in matching. A collating symbol is made up of one or more characters enclosed by the special brackets [. and .].

One or more characters that are treated as a single character in matching are called a collating element. Precisely, a bracket expression pattern represents a set of collating elements and a bracket expression matches a collating element rather than a character, but we do not differentiate them for brevity here.

For example, the character combination “ch” was treated as a single character in the traditional Spanish language. If this character combination is registered as a collating element in the locale data, the bracket expression [[.ch.]df] matches one of ch, d, and f.

Equivalence classes¶

An equivalence class represents a set of characters that are considered equivalent. A equivalence class is made up of a character (or more precisely, a collating element) enclosed by the special brackets [= and =].

An equivalence class represents the set of characters that consists of the character enclosed by the brackets and the characters that are in the same primary equivalence class as the enclosed character. The shell consults the locale data for the definition of equivalence classes in the current locale.

For example, if the six characters a, à, á, â, ã, ä are defined to be in the same primary equivalence class, the bracket expressions [[=a=]], [[=à=]], and [[=á=]] match one of the six.

Character classes¶

A character class represents a predefined set of characters. A character class is made up of a class name enclosed by the special brackets [: and :]. The shell consults the locale data for which class a character belongs to.

The following character classes can be used in all locales:

[:lower:]

[:upper:]

[:alpha:]

[:digit:]

[:xdigit:]

[:alnum:]

[:blank:]

[:space:]

[:punct:]

[:print:]

[:cntrl:]

For example, the bracket expression [[:lower:][:upper:]] matches a lower or upper case character. In addition to the classes listed above, other classes may be used depending on the definition of the current locale.

Redirection to files¶

The most common type of redirection is redirection to files.

Redirection of input

Redirection of output

Redirection of input and output

The token is subject to the four expansions. It is also subject to pathname expansion if the shell is interactive. The expansion result is treated as the pathname of the file to which redirection is performed. If the pathname expansion does not result in a single pathname, it is an error.

In redirection of input, the standard input is replaced with a file descriptor which is open for read-only access to the target file. If the target file cannot be opened for read-only access, it is an error.

In redirection of output, the standard output is replaced with a file descriptor which is open for write-only access to the target file. If the target file cannot be opened for write-only access, it is an error. If the target file does not exist, a new empty file is created and opened. If the target file already exists, the file is opened as follows:

In redirection of input and output, the standard input is replaced with a file descriptor which is open for read-and-write access to the target file. If the file does not exist, a new empty file is created and opened.

Socket redirection

Duplication of file descriptors¶

Redirection allows duplicating or closing existing file descriptors.

Duplication of file descriptor

The token is subject to expansion as in redirection to files, but it is treated as a file descriptor rather than a pathname. Thus the expanded token must be a non-negative integer.

The <& and >& operators duplicate the file descriptor specified by token to the standard input and output, respectively. (The operators can be prefixed with a non-negative integer so that the file descriptor is duplicated to a file descriptor other than the standard input or output.)

If the expanded token is a single hyphen rather than a non-negative integer, the file descriptor is closed rather than duplicated. By default, the <& and >& operators close the standard input and output, respectively, but the operators can be prefixed with a non-negative integer so that another file descriptor is closed.

In the POSIXly-correct mode, a file descriptor must be readable when duplicated by the <& operator and writable when duplicated by the >& operator.

Here documents and here strings¶

Here document and here string allow redirection to file descriptors that reads strings directly specified in shell commands.

Here document

Here string

In a here document or here string, the standard input is replaced with a readable file descriptor. When the command reads from the file descriptor, it will read the contents of the here document/string, which is defined below.

When a here document operator (<< or <<-) appears in a command, the shell reads the contents of the here document starting from the next line. The contents of here documents are not parsed nor executed as commands. The token after the operand specifies a delimiter that indicates the end of the contents. (The token is not subject to any expansion, but quotation is processed.) The contents of the here document is terminated just before the first line containing the token only. When using the <<- operator, all tab characters at the beginning of each line in the here document contents are removed and the delimiter token may be preceded by tab characters.

If there are more than one here document operator on one line, the contents of the here documents are parsed in order: The contents of the first here document starts from the next line and ends before the first line containing the token that followed the first operator. Just after that line, the contents of the second here document starts, and so on.

The contents of here documents are treated literally: whitespaces, tabs, etc. remain as is. The exception is that, when the token is not quoted at all:

In here string, the token after the operator is subject to expansion as in redirection to files. The expansion result becomes the contents of the here string. A newline character is automatically appended to the end of here string contents.

Here string is yash’s extension that is not defined in POSIX. Other shells like bash, ksh, and zsh have the same feature.

Pipeline redirection¶

Pipeline redirection allows opening pipelines that can be used for arbitrary purposes.

Pipeline redirection

The token is subject to expansion as in redirection to files, but it is treated as a file descriptor rather than a pathname. Thus the expanded token must be a non-negative integer.

Pipeline redirection opens a new pipeline. The standard output (or the file descriptor specified before the operator, if any) is replaced with the file descriptor open for writing to the pipeline. The file descriptor specified by token is replaced with the file descriptor open for reading from the pipeline.

Pipeline redirection is yash’s extension that is not defined in POSIX.

Process redirection¶

Process redirection creates a pipeline connected to another command.

Process redirection

In process redirection, the command specified is executed in a subshell. If the process redirection is of the form <(command...), the standard output of command is connected with a pipeline to the standard input of the command the redirection is associated with. If the process redirection is of the form >(command...), the standard input of command is connected with a pipeline to the standard output of the command the redirection is associated with.

Process redirection is yash’s extension that is not defined in POSIX. Bash and zsh have a feature called process substitution, which uses the same syntax as yash’s process redirection, but incompatibly differs in behavior.

Execution of simple commands¶

A simple command is executed as follows:

Command search

Termination of the shell¶

The shell exits when it reached the end of input and has parsed and executed all input commands or when the exit built-in is executed. The exit status of the shell is that of the last command the shell executed (or zero if no commands were executed). The exit status of the shell is always between 0 and 255 (inclusive). If the exit status of the last command is 256 or larger, the exit status of the shell will be the remainder of the exit status divided by 256.

If an exit handler has been registered by the trap built-in, the handler is executed just before the shell exits. The exit status of the commands executed in the handler does not affect the exit status of the shell.

If a non-interactive shell encountered one of the following errors, the shell immediately exits with a non-zero exit status:

Functions¶

Functions allow executing a compound command as a simple command. A function can be defined by the function definition command and executed by a simple command. You can use the unset built-in to remove function definitions.

There are no functions predefined when yash is started.

A function is executed by executing its body, which is a compound command. While the function is being executed, positional parameters are set to the arguments given to the function. The old positional parameters are restored when the function execution finishes.

Local variables

Command execution environment¶

The shell holds following properties during execution.

Those properties are inherited from the invoker of the shell to the shell, and from the shell to each external command executed by the shell.

The properties can be changed during the execution of the shell by built-in commands, variable assignments, etc.

Subshells

Prompts¶

The interactive shell prints a prompt just before it reads a command. The contents of the prompt is specified by the value of the PS1 and PS2 variables. The former is used for reading the first line of the command and the latter for other lines.

When the prompt is printed, the variable value is subjected to parameter expansion, command substitution, and arithmetic expansion (but note that the POSIX standard requires parameter expansion only). The result of the expansion is parsed by the rules below to make the actual prompt string, which is printed to the standard error.

In the POSIXly-correct mode, each exclamation mark (!) in the string is substituted with the command history number of the command that is being input. Two adjacent exclamation marks (!!) are printed as a single exclamation. Other characters are printed intact.

If the shell is not in the POSIXly-command mode, the following notations can be used to format the prompt string. Notations are replaced with the strings designated in the list below. Characters that are not interpreted as notations are printed intact.

\a

\e

\j

\n

\r

\!

\$

\\

\[, \]

\ffontspecs.

In addition to the normal prompt, a prompt string can be displayed to the right of the cursor if line-editing is active. Those prompts are called right prompts. The contents of right prompts are defined by the value of the PS1R and PS2R variables, each corresponding to the PS1 and PS2 variables.

Using the above-said notations, the font style of command strings the user inputs can be changed as well as that of prompts. The font style of command strings is defined by the value of the PS1S and PS2S variables, each corresponding to the PS1 and PS2 variables. The value can contain the \ffontspecs. notation only. If you enable command line prediction, the predicted part of the command line can also be styled with the PS1P and PS2P variables.

When the shell is not in the POSIXly-correct mode, the prompt variables can be defined with a name prefixed with YASH_ (e.g. YASH_PS1). This allows using a different prompt string than that in the POSIXly-correct mode.

When the shell is not in the POSIXly-correct mode, the value of the PROMPT_COMMAND variable is executed before each prompt.

Command history¶

Command history is a feature of the shell that remembers executed commands to allow re-executing them later. Commands executed in the interactive mode are automatically saved in the command history. Saved commands can be edited and re-executed using line-editing and the fc and history built-ins.

Commands are saved line by line. Lines that do not contain any non-whitespace characters are not saved in the history. Lines that start with whitespaces are not saved when the hist-space option is on.

Command history is saved in a file. When history is first used after an interactive shell was started, the shell opens a file to save history in. The filename is specified by the value of the HISTFILE variable. If the file contains history data when opened, the data is restored to the shell’s history. The file contents are updated in real time as the user inputs commands into the shell. If the HISTFILE variable is not set or the file cannot be opened successfully, history is not saved in the file, but the history feature will be functional in all other respects.

The number of commands saved in history is specified by the value of the HISTSIZE variable. The shell automatically removes old history data so that the number of saved commands does not exceed the value. If the HISTSIZE variable is not set or its value is not a natural number, 500 items will be saved in history.

The shell looks at the value of the HISTFILE and HISTSIZE variables only when the history feature is first used after the shell was started. “The history feature is used” when:

Therefore, the variables should be set in initialization scripts.

When more than one instance of yash shares a single history file, all the shells use the same history data. As a result, commands that have been executed by a shell instance can be recalled on another shell instance. Shells sharing the same history should have the same HISTSIZE value so that they manipulate history data properly.

Yash’s history data file has its own format that is incompatible with other kinds of shells.

The HISTRMDUP variable can be set to remove duplicate history items.

Mail checking¶

An interactive shell can notify receipt of email. The shell periodically checks the modification date/time of a file specified by the user. If the file has been modified since the previous check, the shell prints a notification message (except when the shell is not in the POSIXly-correct mode and the file is empty). By specifying a mailbox file to be checked, the shell will print a message when the file has been modified, that is, some mail has been received.

Check is done just before the shell prints a command line prompt. The interval of checks can be specified by the MAILCHECK variable in seconds. If the variable value is 0, check is done before every prompt. If the variable value is not a non-negative integer, no checks are done.

The file whose modification time is checked is specified by the MAIL variable. The variable value should be set to the pathname of the file.

If you want to check more than one file or customize the notification message, you can set the MAILPATH variable instead of the MAIL variable. When the MAILPATH variable is set, the MAIL variable is ignored. The value of the MAILPATH variable should be set to one or more colon-separated pathnames of files to be checked. Each pathname can be followed by a percent sign (%) and a custom notification message, which is printed when the corresponding file has been modified. If the pathname contains a percent sign, it should be quoted by a backslash. The specified message is subject to parameter expansion. For example, if the value of the MAILPATH variable is /foo/mail%New mail!:/bar/mailbox%You've got mail:/baz/mail\%data, the shell will print

Job ID¶

Some built-ins use the following notation, which is called job ID, to specify a job to operate on:

%, %%, %+

%-

%n

%string

%?string

The current job and previous job are jobs selected by the shell according to the following rules:

Yash has some options to modify the rules of the current/previous job selection. (The rules above have priority over the options below.)

cur-async

cur-bg

cur-stop

The current and previous jobs are not changed as long as the rules above are met.

The rules of the current/previous job selection defined in the POSIX standard are looser than yash’s rules above. Other POSIX-compliant shells may select the current and previous jobs differently.

Types of built-in commands¶

Yash has several types of built-in commands described below.

Special built-in commands are the most important kinds of built-in commands. They are executed regardless of whether the corresponding external commands exist or not. Results of variable assignments that occur in a simple command that invokes a special built-in last after the command has finished. Moreover, in the POSIXly-correct mode, a non-interactive shell immediately exits with a non-zero exit status when an error occurs in a simple command executing a special built-in.

Mandatory built-in commands and elective built-in commands are similar to special built-ins in that they do not need external commands to be executed but differ in that they may be overridden by functions. While mandatory built-ins are always available, you cannot use elective built-ins in the POSIXly-correct mode because POSIX only reserves their names without defining their behavior.

An extension built-in command is a built-in that is not mentioned in POSIX. Like an elective built-in, it can be executed without an external command when the POSIXly-correct mode is off. However, when the POSIXly-correct mode is on, the shell works as if the built-in does not exist.

Substitutive built-in commands work on behalf of external commands found in PATH. These built-ins improve execution speed by bypassing invocation overheads for external programs.

Syntax of command arguments¶

In this section we explain common rules about command arguments. The built-in commands of yash follow the rules unless otherwise stated.

There are two types of command arguments. One is options and the other is operands. An option is an argument that starts with a hyphen (-) and changes the way the command behaves. Some options take arguments. An operand is an argument that is not an option and specifies objects the command operates on.

If you specify more than one option to a command, the order of the options are normally not significant. The order of operands, however, affects the command behavior.

An option is either a single-character option or a long option. A single-character option is identified by one alphabetic character. A long option is identified by multiple alphabetic characters. The POSIX standard only prescribes single-character options, so in the POSIXly-correct mode you cannot use long options.

A single-character option is composed of a hyphen followed by a letter. For example, -a is a single-character option. A single-character option that takes an argument requires the argument to be just after the option name.

Example 4. The set built-in and single-character options

For the set built-in, -m is a single-character option that does not take an argument and -o is one that takes an argument.

In these two command lines, errexit is the argument to the -o option.

In the second example above, the -o option and its argument are combined into a single command line argument. The POSIX standard deprecates that style and any POSIX-conforming applications must specify options and their arguments as separate command line arguments, although yash accepts both styles.

You can combine single-character options that do not take arguments into a single command line argument. For example, the three options -a, -b and -c can be combined into -abc.

A long option is composed of two hyphens followed by an option name. For example, --long-option is a long option. You can omit some last characters of a long option name as long as it is not ambiguous. For example, you can use --long instead of --long-option if there is no other options beginning with --long. Like a single-character option, a long option that takes an argument requires the argument to be a command line argument just after the option name or to be specified in the same command line argument as the option name, separated by an equal sign (=).

Example 5. The fc built-in and long options

For the fc built-in, --quiet is a long option that does not take an argument and --editor is one that takes an argument.

In these command lines, vi is the argument to the --editor option.

Arguments that are not options (nor arguments to them) are interpreted as operands. The POSIX standard requires all options should be specified before any operands. Therefore, in the POSIXly-correct mode, any arguments that come after the first operand are interpreted as operands (even if they look like options). If not in the POSIXly-correct mode, you can specify options after operand.

Regardless of whether the shell is in the POSIXly-correct mode or not, an argument that is just composed of two hyphens (--) can be used as a separator between options and operands. All command line arguments after the -- separator are interpreted as operands, so you can specify operands that start with a hyphen correctly using the separator.

Example 6. Options and operands to the set built-in

In this example, -a and -b are options and -c and -d are operands. The -- separator itself is neither an option nor an operand.

Regardless of whether the shell is in the POSIXly-correct mode or not, an argument that is just composed of a single hyphen (-) is interpreted as an operand.

Shell options on line-editing¶

The following options can be set by the set built-in to enable line-editing and choose an editing mode to activate:

vi

emacs

The other line-editing-related options are:

le-always-rp

le-comp-debug

le-conv-meta

le-no-conv-meta

le-predict

le-predict-empty

le-prompt-sp

le-visible-bell

le-trim-right

Editing modes¶

The vi mode is an editing mode that offers key bindings similar to that of the vi editor. The vi mode has two sub-modes that are switched during editing: the insert and command modes. The sub-mode is always reset to the insert mode when line-editing is started for a new command line. In the insert mode, most characters are inserted to the buffer as typed. In the command mode, input characters are treated as commands that move the cursor, insert/delete text, etc.

The emacs mode offers key bindings similar to the emacs editor. Most characters are inserted to the buffer as typed, but more characters are treated as commands than the vi insert mode.

Another sub-mode is used while you enter search keywords. The sub-mode is called the search mode, which offers slightly different key bindings depending on the active editing mode.

Line-editing commands¶

All characters the user enters while line-editing is active are treated as line-editing commands listed below. The bindkey built-in allows customizing the key bindings of each mode (except for the search mode).

The list below shows not only the functions of commands but also the default key bindings. The keywords “vi-insert”, “vi-command”, “vi-search”, “emacs”, “emacs-search” means the vi insert mode, the vi command mode, the search mode for the vi mode (the vi search mode), the emacs mode, and the search mode for the emacs mode (the emacs search mode), respectively.

Some commands take an argument that affects the function of the commands. For example, the forward-char command moves the cursor by as many characters as specified by the argument. To specify an argument, use the digit-argument command just before another command that takes an argument.

Basic editing commands

Motion commands

Editing commands

Completion commands

Vi-specific commands

Emacs-specific commands

History-related commands

Search mode commands

Escape sequences¶

In the bindkey built-in, escape sequences are used to represent special keys such as function keys and arrow keys. Every escape sequence starts with a backslash (\) and thus there is also an escape sequence for a backslash itself.

Below are available escape sequences:

\\

\B

\D

\E

\H

\I

\L

\N

\P

\R

\U

\X

\!

\#

\$

\?

\^@

\^A, \^B, ..., \^Z

\^[

\^\

\^]

\^^

\^_

\^?

\F00, \F01, ..., \F63

\a1

\a3

\b2

\bg

\bt

\c1

\c3

\ca

\cl

\cn

\co

\cp

\cr

\cs

\ct

\dl

\ei

\el

\es

\et

\ex

\fd

\hp

\il

\ll

\me

\mk

\ms

\mv

\nx

\on

\op

\pr

\pv

\rd

\re

\rf

\rh

\rp

\rs

\sf

\sl

\sr

\st

\su

\sv

\ud

\SE

\SH

\SI

\SL

\SR

\SX

\Sbg

\Scn

\Sco

\Scp

\Scr

\Sdl

\Sel

\Sex

\Sfd

\Shp

\Smg

\Smv

\Snx

\Sop

\Spr

\Spv

\Srd

\Sre

\Srp

\Ssu

\Ssv

\Sud

INTR, EOF, KILL, and ERASE are special characters configured by the stty command. In a typical configuration, they are sent by typing Ctrl+C, Ctrl+D, Ctrl+U, and Ctrl+H, respectively, but some configuration uses Ctrl+? instead of Ctrl+H for ERASE.

Command line completion¶

By using the complete and complete-next-candidate commands, etc., you can complete command names, options, and operands. By default, the complete-next-candidate command is bound with the Tab key in the vi insert and emacs modes.

Type a few first letters of a command name or pathname and hit the Tab key, and a list of matching names will be shown. You can choose a candidate from the list to complete the name by hitting the Tab key again. If there is only one matching name, no list will be shown and the name will directly be completed.

If the name to be completed contains characters like * and ?, it is treated as a pattern. The name on the command line will be directly substituted with all possible names matching the pattern (you cannot choose from a list).

Normally, command names are completed with command names and command arguments with pathnames. However, completion functions can be defined to refine completion results.

Completion details

Command line prediction¶

This is an experimental feature. When the le-predict option is enabled, the shell automatically tries to predict a command string fragment that follows the part of the command you have already typed in line-editing.

For example, assume you have once typed the command ls Documents. Next time you start typing ls Doc, the shell will show uments just after the cursor. If you are satisfied with this suggestion, you can move the cursor to the right by the forward-char or any other motion commands instead of typing the rest of the command. After moving the cursor after the last s, you can use the accept-line command to execute the command. You can also use the accept-prediction command to immediately execute the suggested command without moving the cursor.

To distinguish the typed and predicted parts of a command string, you can change the font style of those parts by setting the PS1S and PS1P variables.

When you move the cursor to the right, the predicted part up to the cursor becomes the typed part as if you actually typed it. Moving the cursor to the left does not turn the typed part back to the prediction. Use deletion commands such as backward-delete-char to delete typed command fragment.

The predicted part of the command is shown only when the cursor is at the end of the typed part.

By default, the predicted part is shown after you start typing a command string. By enabling the le-predict-empty option, the predicted part is also shown before you type the first character of the command string.

The prediction algorithm suggests command fragments on the basis of the command history. The algorithm considers recent history entries more probable. It also takes command succession patterns into account. A predicted command fragment is not always a complete valid command because less probable part of the fragment is excluded from prediction.

How can I use Unicode (non-ASCII) characters?¶

You need to set locale environment variables to enable Unicode character support.

If the variables have already been configured for your preference, you probably don’t have to do anything. To check the current locale configurations, you can use the locale command:

$ locale
LANG=
LC_CTYPE="en_US.utf8"
LC_NUMERIC="en_US.utf8"
LC_TIME="en_US.utf8"
LC_COLLATE="en_US.utf8"
LC_MONETARY="en_US.utf8"
LC_MESSAGES="en_US.utf8"
LC_PAPER="en_US.utf8"
LC_NAME="en_US.utf8"
LC_ADDRESS="en_US.utf8"
LC_TELEPHONE="en_US.utf8"
LC_MEASUREMENT="en_US.utf8"
LC_IDENTIFICATION="en_US.utf8"
LC_ALL=en_US.utf8

In this example, the locale command shows that all the locale setting categories are configured for the English language, the United States region, and the UTF-8 encoding.

If the current configuration does not seem to match your preference, set the LC_ALL variable like this:

export LC_ALL=en_US.utf8

If you want to use other languages, regions, or encodings, you have to set the variable to a different value. Please consult your OS’s documentation to learn how to configure these variables in detail.

If you want to apply the same configuration every time you start yash, write the command in ~/.yashrc or ~/.yash_profile.

If yash still rejects Unicode characters being entered, see the section below regarding line-editing.

Line-editing does not work¶

First, type echo $TERM and see if it prints a sane value. xterm is the safest value that should work on any existing environment. Colored versions like xterm-16color and other terminal types like rxvt and vt100 may also work. All possible values can be listed by the toe command. It’s most desirable to choose a value that matches the actual terminal type you are using, but it might not work if the terminal type you chose is not supported on the system on which yash is running. If so, try changing the TERM value by export TERM=xterm, for example, to find a value that works.

If line-editing works but you have trouble entering Unicode (non-ASCII) characters, try enabling the le-no-conv-meta option by set -o le-no-conv-meta.

Tokenization¶

The characters of the input source code are first delimited into tokens. Tokens are delimited so that the earlier token spans as long as possible. A sequence of one or more unquoted blank characters delimits a token.

The following tokens are the operator tokens:

& && ( ) ; ;; | || < << <& <( <<- <<< <> > >> >& >( >>| >| (newline)

Characters that are not blank nor part of an operator compose a word token. Words are parsed by the following parsing expression grammar:

Word

WordElement

QuoteElement

Parameter

PortableName

ParameterBody

ParameterNumber

ParameterName

ParameterIndex

ParameterIndexWord

ParameterMatch

ParameterMatchWord

ParameterMatchWordNoSlash

Arithmetic

ArithmeticBody

CommandSubstitution

CommandSubstitutionQuoted

CommandSubstitutionBody

CommandSubstitutionBodyQuoted

SpecialChar

The set of terminals of the grammar is the set of characters that can be handled on the environment in which the shell is run (a.k.a. execution character set), with the exception that the set does not contain the null character ('\0').

Strictly speaking, the definition above is not a complete parsing expression grammar because the rule for CommandSubstitution (Quoted) depends on CompleteProgram which is a non-terminal of the syntax.

Token classification

Comments

Syntax¶

After tokens have been delimited, the sequence of the tokens is parsed according to the context-free grammar defined below, where *, +, and ? should be interpreted in the same manner as standard regular expression:

CompleteProgram

CompoundList

AndOrList

Pipeline

Command

CompoundCommand

Subshell

Grouping

IfCommand

ForCommand

WhileCommand

CaseCommand

CaseList

CaseItem

DoubleBracketCommand

Ors

Ands

Nots

Primary

FunctionCommand

FunctionDefinition

SimpleCommand

Assignment

Redirection

RedirectionOperator

NL

In the rule for Primary, Word tokens must not be ]]. Additionally, if a Primary starts with a Word, it must not be any of the possible unary operators allowed in the rule.

In the rule for SimpleCommand, a Word token is accepted only when the token cannot be parsed as the first token of an Assignment.

In the rule for Assignment, the ( token must immediately follow the AssignmentPrefix token, without any blank characters in between.

Here-document contents do not appear as part of the grammar above. They are parsed just after the newline (NL) token that follows the corresponding redirection operator.

Alias substitution

Syntax¶

Description¶

The alias built-in defines and/or prints aliases as specified by operands. The printed aliases can be used as (part of) shell commands. The built-in prints all currently defined aliases when given no operands.

Options¶

-g, --global

-p, --prefix

Operands¶

name

name=value

Exit status¶

The exit status of the alias built-in is zero unless there is any error.

Notes¶

The characters that cannot be used in an alias name are the space, tab, newline, and any of =$<>\'"`;&|()#. You can use any characters in an alias value.

The alias built-in is a mandatory built-in.

The POSIX standard defines no options for the alias built-in, thus no options are available in the POSIXly correct mode.

Syntax¶

Description¶

When executed without any option or operands, the built-in prints all array definitions to the standard output in a form that can be parsed as commands.

When executed with name and values (but without an option), the built-in sets the values as the values of the array named name.

With the -d (--delete) option, the built-in removes the indexth values of the array named name. The number of values in the array will be decreased by the number of the indexes specified. If the indexth value does not exist, it is silently ignored.

With the -i (--insert) option, the built-in inserts values into the array named name. The number of values in the array will be increased by the number of the values specified. The values are inserted between the indexth and next values. If index is zero, the values are inserted before the first value. If index is larger than the number of values in the array, the values are appended after the last element.

With the -s (--set) option, the built-in sets value as the indexth value of the array named name. The array must have at least index values.

Options¶

-d, --delete

-i, --insert

-s, --set

Operands¶

name

index

value

Exit status¶

The exit status of the array built-in is zero unless there is any error.

Notes¶

The array built-in is not defined in the POSIX standard. Yash implements the built-in as an extension.

The command array name value... is equivalent to the assignment name=(value...).

Syntax¶

Description¶

The bg built-in sends the SIGCONT signal to the specified job. As a result, the job is resumed in the background (if it has been suspended).

The name of the job is printed when the job is resumed.

The built-in can be used only when job control is enabled.

Operands¶

job

Exit status¶

The exit status of the bg built-in is zero unless there is any error.

Notes¶

The bg built-in is a mandatory built-in.

The POSIX standard provides that the built-in shall have no effect when the job is already running. The bg built-in of yash, however, always sends the SIGCONT signal to the job.

Syntax¶

Description¶

When executed with the -l (--list) option, the built-in lists all available line-editing commands to the standard output.

When executed with one of the other options, the built-in prints or modifies key bindings for the editing mode specified by the option:

Options¶

-a, --vi-command

-e, --emacs

-v, --vi-insert

Operands¶

key

command

Exit status¶

The exit status of the bindkey built-in is zero unless there is any error.

Notes¶

The bindkey built-in is an elective built-in. It cannot be used in the POSIXly-correct mode because POSIX does not define its behavior.

Syntax¶

Description¶

When executed without the -i (--iteration) option, the built-in aborts a currently executed for, while, or until loop. When executed in nested loops, it aborts the nestth innermost loop. The default nest is one. If the number of currently executed nested loops is less than nest, the built-in aborts the outermost loop.

When executed with the -i (--iteration) option, the built-in aborts the currently executed (innermost) iterative execution.

Options¶

-i, --iteration

Operands¶

nest

Exit status¶

The exit status of the break built-in is:

Notes¶

The break built-in is a special built-in.

The POSIX standard defines no options for the break built-in; the built-in accepts no options in the POSIXly-correct mode.

Treatment of currently executed loops that are not lexically enclosing the break built-in is unspecified in POSIX. Examples of such loops include:

Yash does not allow breaking such loops.

Syntax¶

Description¶

The cd built-in changes the working directory to the directory specified by the operand.

The pathname of the new working directory is assigned to the PWD variable, whose previous value is again assigned to the OLDPWD variable. The new PWD value will not contain any . or .. components except when the shell is in the POSIXly-correct mode and the new pathname begins with /...

If directory is a relative path that does not start with ‘.’ or ‘..’, paths in the CDPATH variable are searched to find a new working directory. The search is done in a manner similar to the last step of command search, but a directory is sought instead of an executable regular file. If a new working directory was found from CDPATH, its pathname is printed to the standard output. If no applicable directory was found in the search, directory is simply treated as a pathname relative to the current working directory.

If the working directory was successfully changed, the value of the YASH_AFTER_CD variable is executed as a command unless the shell is in the POSIXly-correct mode. If the variable is an array, its values are executed iteratively (cf. eval built-in).

Options¶

-L, --logical

-P, --physical

--default-directory=directory

The -L (--logical) and -P (--physical) options are mutually exclusive: only the last specified one is effective. If neither is specified, -L is assumed.

Operands¶

directory

Exit status¶

The exit status of the cd built-in is zero if the working directory was successfully changed and non-zero if there was an error.

Notes¶

The cd built-in is a mandatory built-in.

The POSIX standard does not define the use of the YASH_AFTER_CD variable or the --default-directory=... option. The standard does not allow using an option with a single hyphen operand.

The exit status of the commands in the YASH_AFTER_CD variable does not affect that of the cd built-in.

Syntax¶

Description¶

The colon built-in does nothing. Any command line arguments are ignored.

Exit status¶

The exit status of the colon built-in is zero.

Notes¶

The colon built-in is a special built-in.

Arguments are expanded and redirections are performed as usual. The colon and true built-ins have the same effect, but colon is a special built-in while true is a mandatory.

Syntax¶

Description¶

Without the -v (--identify) or -V (--verbose-identify) option, the built-in executes command with arguments in the same manner as the last step of execution of simple commands. The command is treated as a built-in or external command or a function according to the options specified to the command built-in. The shell does not exit on argument syntax error etc. even if the command is a special built-in

With the -v (--identify) option, command is identified. If the command is found in $PATH, its full pathname is printed. If it is a keyword, function, or built-in that is not found in $PATH, the command name is simply printed. If it is an alias, it is printed in the form like alias ll='ls -l'. If the command is not found, nothing is printed and the exit status is non-zero.

The -V (--verbose-identify) option is similar to the -v (--identify) option, but the output format is more human-friendly.

Options¶

-a, --alias

-b, --builtin-command

-e, --external-command

-f, --function

-k, --keyword

-p, --standard-path

-v, --identify

-V, --verbose-identify

If none of the -a (--alias), -b (--builtin-command), -e (--external-command), -f (--function), and -k (--keyword) options is specified, the following defaults are assumed:

Without the -v (--identify) or -V (--verbose-identify) option

With the -v (--identify) or -V (--verbose-identify) option

Operands¶

command

argument...

Exit status¶

The exit status of the command built-in is:

Without the -v (--identify) or -V (--verbose-identify) option

With the -v (--identify) or -V (--verbose-identify) option

Notes¶

The command built-in is a mandatory built-in.

In the POSIXly-correct mode, options other than -p, -v, and -V cannot be used and at most one command can be specified. The POSIX standard does not allow specifying both -v and -V together, but yash does (only the last specified one is effective).

Syntax¶

Description¶

The built-in generates completion candidates according to the specified arguments. No matter how candidates are generated, only candidates that match the word being completed are generated.

Options¶

-A pattern, --accept=pattern

-D description, --description=description

-O, --option

-P prefix, --prefix=prefix

-R pattern, --reject=pattern

-S suffix, --suffix=suffix

-T, --no-termination

Options that select candidate types

Operands¶

Operands are treated as completion candidates.

Exit status¶

The exit status of the built-in is zero if one or more candidates were generated, one if no candidates were generated, or larger than one if an error occurred.

Notes¶

The complete built-in is an elective built-in. It can be used in completion functions even in the POSIXly-correct mode because the mode is temporarily disabled during completion.

Syntax¶

Description¶

When executed without the -i (--iteration) option, the built-in aborts the current iteration of for, while, or until loop and starts the next iteration of the loop. When executed in nested loops, it affects the nestth innermost loop. The default nest is one. If the number of currently executed nested loops is less than nest, the built-in affects the outermost loop.

When executed with the -i (--iteration) option, the built-in aborts the current iteration of (innermost) iterative execution.

Options¶

-i, --iteration

Operands¶

nest

Exit status¶

The exit status of the continue built-in is:

Notes¶

The continue built-in is a special built-in.

The POSIX standard defines no options for the continue built-in; the built-in accepts no options in the POSIXly-correct mode.

Treatment of currently executed loops that are not lexically enclosing the continue built-in is unspecified in POSIX. Examples of such loops include:

Yash does not allow continuing such loops.

Syntax¶

Description¶

The directory stack is a feature that records history of working directories. You can use the pushd built-in to save a working directory in the directory stack, the popd built-in to recall the saved working directory, and the dirs built-in to see the stack contents. Those built-ins use the DIRSTACK array and the PWD variable to save the stack contents. Modifying the array means modifying the stack contents.

Directory stack entries are indexed by signed integers. The entry of index +0 is the current working directory, +1 is the last saved directory, +2 is the second last, and so on. Negative indices are in the reverse order: the entry of index -0 is the first saved directory, -1 is the second, and -n is the current working directory if the stack has n entries,

When executed without the -c (--clear) option, the dirs built-in prints the current contents of the directory stack to the standard output. With the -c (--clear) option, the built-in clears the directory stack.

Options¶

-c, --clear

-v, --verbose

Operands¶

index

Exit status¶

The exit status of the dirs built-in is zero unless there is any error.

Notes¶

The dirs built-in is an elective built-in. It cannot be used in the POSIXly-correct mode because POSIX does not define its behavior.

Syntax¶

Description¶

The disown built-in removes the specified jobs from the job list. The removed jobs will no longer be job-controlled, but the job processes continue execution (unless they have been suspended).

Options¶

-a, --all

Operands¶

job

Exit status¶

The exit status of the disown built-in is zero unless there is any error.

Notes¶

The disown built-in is an elective built-in. It cannot be used in the POSIXly-correct mode because POSIX does not define its behavior.

Syntax¶

Description¶

The dot built-in reads the specified file, parses its contents as commands, and executes them in the current command execution environment.

If arguments are specified, positional parameters are temporarily set to them. The positional parameters will be restored when the dot built-in finishes. If no arguments are specified, the positional parameters are not changed.

If file does not contain any slashes, the shell searches $PATH for a readable (but not necessarily executable) shell script file whose name is file in the same manner as command search. If no such file was found, the shell searches the current working directory for a file unless in the POSIXly-correct mode. To ensure that the file in the current working directory is used, start file with ‘./’.

Options¶

-A, --no-alias

-L, --autoload

The dot built-in treats as operands any command line arguments after the first operand.

Operands¶

file

arguments...

Exit status¶

The exit status of the dot built-in is that of the last command executed. The exit status is zero if the file contains no commands to execute and non-zero if a file was not found or could not be opened.

Notes¶

The dot built-in is a special built-in.

A non-interactive shell immediately exits with a non-zero exit status if the dot built-in fails to find or open a file to execute.

The POSIX standard defines no options for the dot built-in; the built-in accepts no options in the POSIXly-correct mode.

The POSIX standard does not define the arguments... operands. It is an error to specify the arguments... operands in the POSIXly-correct mode.

Syntax¶

The built-in treats all command line arguments as operands except for the options described below. Any word that cannot be parsed as an acceptable option is treated as an operand. Options must precede all operands. Syntax errors never happen in the echo built-in.

Description¶

The echo built-in prints the operand strings followed by a newline to the standard output. The strings are each separated by a space.

Escape sequences

ECHO_STYLE variable

Options¶

-n

-e

-E

Exit status¶

The exit status of the echo built-in is zero unless there is any error.

Notes¶

The POSIX standard does not define the ECHO_STYLE variable nor any options for the built-in. According to POSIX, the behavior of the built-in is implementation-defined when the first argument is -n or when any argument contains a backslash. For maximum portability, the printf built-in should be preferred over the echo built-in.

Although many values for the ECHO_STYLE variable are defined on the basis of other existing implementations, yash is not intended to exactly imitate those originals. Zsh’s echo built-in interprets a single hyphen argument as a separator between options and operands. Yash does not support such use of hyphen.

Syntax¶

The eval built-in requires that all options precede operands. Any command line arguments after the first operand are all treated as operands.

Description¶

The eval parses operands as commands and executes them in the current command execution environment.

When executed without the -i (--iteration) option, all the operands are concatenated into one string (with a space inserted between each operand) and parsed/executed at once.

With the -i (--iteration) option, the built-in performs iterative execution: operands are parsed/executed one by one. If the continue built-in is executed with the -i (--iteration) option during the iterative execution, the execution of the current operand is aborted and the next operand is parsed/executed immediately. The break built-in with the -i (--iteration) option is similar but the remaining operands are not parsed/executed. The value of the ? special parameter is saved before the iterative execution is started. The parameter value is restored to the saved one after each iteration.

Options¶

-i, --iteration

Operands¶

command

Exit status¶

The exit status is zero if no command was specified or command contained no actual command that can be executed. Otherwise, that is, if the eval built-in executed one or more commands, the exit status of the eval built-in is that of the last executed command.

Notes¶

The eval built-in is a special built-in.

The POSIX standard defines no options for the eval built-in; the built-in accepts no options in the POSIXly-correct mode.

Syntax¶

The exec built-in requires that all options precede operands. It is important so that options to the exec built-in are not confused with options to command. Any command line arguments after command are treated as arguments.

Description¶

When the exec built-in is executed with command, the shell executes command with arguments in a manner similar to the last step of execution of a simple command. The differences are that command is always treated as an external command ignoring any existing functions and built-ins and that the exec system call that starts the external command is called in the current command execution environment instead of a subshell, replacing the shell process with the new command process.

If the shell is in the POSIXly-correct mode or not interactive, failure in execution of command causes the shell to exit immediately.

If an interactive shell that is not in the POSIXly-correct mode has a stopped job, the shell prints a warning message and refuses to execute command. Once the shell process is replaced with an external command, information about the shell’s jobs is lost, so you will have to resume or kill the stopped jobs by sending signals by hand. To force the shell to execute command regardless, specify the -f (--force) option.

When executed without command, the built-in does nothing. As a side effect, however, redirection applied to the built-in remains in the current command execution environment even after the built-in finished.

Options¶

-a name, --as=name

-c, --clear

-f, --force

Operands¶

command

argument...

Exit status¶

If the shell process was successfully replaced with the external command, there is no exit status since the shell process no longer exists.

The exit status is:

Notes¶

The exec built-in is a special built-in.

The POSIX standard defines no options for the exec built-in; the built-in accepts no options in the POSIXly-correct mode.

Syntax¶

Description¶

The exit built-in causes the current shell (or subshell) process to exit.

If an interactive shell has a stopped job, the shell prints a warning message and refuses to exit. To force the shell to exit regardless, specify the -f (--force) option or execute the built-in twice in a row.

If an EXIT trap has been set, the shell executes the trap before exiting.

Options¶

-f, --force

Operands¶

exit_status

Exit status¶

Because the built-in causes the shell to exit, there is no exit status of the built-in.

As an exception, if the shell refused to exit, the exit status of the built-in is non-zero.

Notes¶

The exit built-in is a special built-in.

The POSIX standard defines no options for the exit built-in; the built-in accepts no options in the POSIXly-correct mode.

The POSIX standard provides that the exit_status operand should be between 0 and 255 (inclusive). Yash accepts integers larger than 255 as an extension.

If the built-in is executed during an EXIT trap, the shell just exits without executing the trap again. If exit_status was not specified, the exit status of the shell is what the exit status would be if the trap had not been set. See also Termination of the shell.

Syntax¶

Description¶

The export built-in is equivalent to the typeset built-in with the -gx option.

Notes¶

The export built-in is a special built-in.

The POSIX standard defines the -p option only; other options cannot be used in the POSIXly-correct mode. The POSIX does not allow using the option together with operands.

Syntax¶

Description¶

The false built-in does nothing. Any command line arguments are ignored.

Exit status¶

The exit status of the false built-in is non-zero.

Notes¶

The false built-in is a mandatory built-in.

Syntax¶

Description¶

When executed without the -l (--list) option, the built-in executes the commands in the command history range specified by the operands. If the -s (--silent) option is not specified, the shell invokes an editor which allows you to edit the commands before they are executed. The commands are executed when you quit the editor. If the -s (--silent) option is specified, the commands are immediately executed. In either case, the executed commands are printed to the standard output and added to the history.

When executed with the -l (--list) option, the built-in prints the commands in the command history range specified by the operands. By default, commands are printed with their history entry numbers, but output format can be changed using the -n (--no-numbers)) and -v (--verbose) options.

Options¶

-e editor, --editor=editor

-l, --list

-n, --no-numbers

-q, --quiet

-r, --reverse

-s, --silent

-v, --verbose

Operands¶

start and end

old=new

Exit status¶

If commands was executed, the exit status of the fc built-in is that of the last executed command. Otherwise, the exit status is zero unless there is any error.

Notes¶

The fc built-in is a mandatory built-in.

The POSIX standard does not define the -q (--quiet) or -v (--verbose) options, so they cannot be used in the POSIXly-correct mode.

Command history cannot be modified during line-editing.

Syntax¶

Description¶

The fg built-in brings the specified job to the foreground and sends the SIGCONT signal to the job. As a result, the job is resumed in the foreground (if it has been suspended). The built-in then waits for the job to finish and returns the exit status of it.

The name of the job is printed when the job is resumed. When not in the POSIXly-correct mode, the job number is also printed.

The built-in can be used only when job control is enabled.

Operands¶

job

Exit status¶

The exit status of the fg built-in is that of the (last) job resumed. The exit status is non-zero when there was some error.

Notes¶

The fg built-in is a mandatory built-in.

You cannot specify more than one job in the POSIXly-correct mode.

Syntax¶

Description¶

The getopts built-in parses single-character options that appear in arguments. Each time the built-in is invoked, it parses one option and assigns the option character to variable.

The optionlist operand is a list of option characters that should be accepted by the parser. In optionlist, an option that takes an argument should be specified as the option character followed by a colon. For example, if you want the -a, -b and -c options to be parsed and the -b option to take an argument, then optionlist should be ab:c.

When an option that takes an argument is parsed, the argument is assigned to the OPTARG variable.

When an option that is not specified in optionlist is found or when an option argument is missing, the result depends on the first character of optionlist:

The built-in parses one option for each execution. For all options in a set of command line arguments to be parsed, the built-in has to be executed repeatedly with the same arguments. The built-in uses the OPTIND variable to remember which argument should be parsed next. When the built-in is invoked for the first time, the variable value must be 1, which is the default value. You must not modify the variable until all the options have been parsed, when the built-in sets the variable to the index of the first operand in arguments. (If there are no operands, it will be set to the number of arguments plus one.)

When you want to start parsing a new set of arguments, you have to reset the OPTIND variable to 1 beforehand.

Operands¶

optionlist

variable

arguments

Exit status¶

If an option is found, whether or not it is specified in optionlist, the exit status is zero. If there is no more option to be parsed, the exit status is non-zero.

Example¶

aopt=false bopt= copt=false
while getopts ab:c opt
do


  case $opt in


  a) aopt=true ;;


  b) bopt=$OPTARG ;;


  c) copt=true ;;


  \?) return 2 ;;


  esac
done
if $aopt;          then echo Option -a specified;       fi
if [ -n "$bopt" ]; then echo Option -b $bopt specified; fi
if $copt;          then echo Option -c specified;       fi
shift $((OPTIND - 1))
echo Operands are: $*

Notes¶

In arguments that are parsed, options must precede operands. The built-in ends parsing when it encounters the first operand.

The getopts built-in is a mandatory built-in.

The POSIX standard does not specify what will happen when the OPTIND variable is assigned a value other than 1.

In the POSIXly-correct mode, option characters in optionlist must be alphanumeric.

Syntax¶

Description¶

When executed with commands but without options, the built-in immediately performs command path search and caches commands' full paths.

When executed with the -r (--remove) option, it removes the paths of commands (or all cached paths if none specified) from the cache.

When executed without options or commands, it prints the currently cached paths to the standard output.

With the -d (--directory) option, the built-in does the same things to the home directory cache, rather than the command path cache. Cached home directory paths are used in tilde expansion.

Options¶

-a, --all

-d, --directory

-r, --remove

Operands¶

command

user

Exit status¶

The exit status of the hash built-in is zero unless there is any error.

Notes¶

The shell automatically caches command and directory paths when executing a command or performing tilde expansion, so normally there is no need to use this built-in explicitly to cache paths.

Assigning a value to the PATH variable removes all command paths from the cache as if hash -r was executed.

The POSIX standard defines the -r option only: other options cannot be used in the POSIXly-correct mode.

The hash built-in is a mandatory built-in.

Syntax¶

Description¶

The help built-in prints a description of built-ins.

Operands¶

built-ins

Exit status¶

The exit status of the help built-in is zero unless there is any error.

Notes¶

The help built-in is an elective built-in. It cannot be used in the POSIXly-correct mode because POSIX does not define its behavior.

Many built-ins of yash accept the --help option that prints the same description.

Syntax¶

Description¶

The history built-in prints or edits command history.

When executed with an option, the built-in edits history according to the option. If more than one option is specified, each option is processed in order.

When executed with the count operand, the built-in prints the most recent count history entries to the standard output in the same manner as the fc built-in.

When executed with neither options nor operands, the built-in prints the whole history.

Options¶

-c, --clear

-d entry, --delete=entry

-F, --flush-file

-r file, --read=file

-s command, --set=command

-w file, --write=file

Operands¶

count

Exit status¶

The exit status of the history built-in is zero unless there is any error.

Notes¶

The history built-in is an elective built-in. It cannot be used in the POSIXly-correct mode because POSIX does not define its behavior.

Command history cannot be modified during line-editing.

Syntax¶

Description¶

The jobs built-in prints information of jobs the shell is currently controlling.

By default, the following information is printed for each job, line by line:

Options¶

-l, --verbose

-n, --new

-p, --pgid-only

-r, --running-only

-s, --stopped-only

Operands¶

jobs

Exit status¶

The exit status of the jobs built-in is zero unless there is any error.

Notes¶

The jobs built-in is a mandatory built-in.

The POSIX standard defines the -l and -p options only: other options cannot be used in the POSIXly-correct mode. In the POSIXly-correct mode, the effect of the -l option is different in that status is reported for each job rather than for each process.

The process group ID of a job executed by yash is equal to the process ID of the first command of the pipeline that forms the job.

Syntax¶

The kill built-in requires that all options precede operands. Any command line arguments after the first operand are all treated as operands.

Description¶

When executed without the -l option, the built-in sends a signal to processes. The signal sent can be specified by option. The SIGTERM signal is sent if no signal is specified.

When executed with the -l option, the built-in prints information of signals to the standard output. If no signal is specified, information of all signals is printed.

Options¶

Signal-specifying options

Other options

Operands¶

processes

signal

Exit status¶

The exit status of the kill built-in is zero unless there is any error. If the signal was sent to at least one process, the exit status is zero even if the signal was not sent to all of the specified processes.

Notes¶

The kill built-in is a mandatory built-in.

Command arguments that start with a hyphen should be used with care. The command kill -1 -2, for example, sends signal 1 to process group 2 since -1 is treated as a signal-specifying option and -2 as an operand that specifies a process group. The commands kill -- -1 -2 and kill -TERM -1 -2, on the other hand, treats both -1 and -2 as operands.

The POSIX standard does not define the -n or -v options, so they cannot be used in the POSIXly-correct mode. The standard does not allow specifying a signal number as the argument of the -s option or a signal name as the signal operand.

The standard requires signal names to be specified without the SIG prefix, like INT and QUIT. If the shell is not in the POSIXly-correct mode, the built-in accepts SIG-prefixed signal names as well.

Syntax¶

Description¶

The local built-in is equivalent to the typeset built-in except that the -f (--functions) and -g (--global) options cannot be used.

Notes¶

The local built-in is an elective built-in. It cannot be used in the POSIXly-correct mode because POSIX does not define its behavior.

Syntax¶

Description¶

The popd built-in removes the last entry from the directory stack, returning to the previous working directory. If index is given, the entry specified by index is removed instead of the last one.

Operands¶

index

Exit status¶

The exit status of the popd built-in is zero unless there is any error.

Notes¶

It is an error to use this built-in when there is only one directory stack entry.

The popd built-in is an elective built-in. It cannot be used in the POSIXly-correct mode because POSIX does not define its behavior.

Syntax¶

Description¶

The printf built-in formats values according to format and prints them to the standard output. Unlike the echo built-in, the printf built-in does not print a newline automatically.

The formatting process is very similar to that of the printf function in the C programming language. You can use conversion specifications (which start with %) and escape sequences (which start with \) in format. Any other characters that are not part of a conversion specification or escape sequence are printed literally.

Conversion specifications

Escape sequences

Operands¶

format

values

Exit status¶

The exit status of the printf built-in is zero unless there is any error.

Notes¶

The POSIX standard does not precisely define how multibyte characters should be handled by the built-in. When you use the %s conversion specification with precision or the %c conversion specification, you may obtain unexpected results if the formatted value contains a character that is represented by more than one byte. Yash never prints only part of the bytes that represent a single multibyte character because all multibyte characters are converted to wide characters when processed in the shell.

If the shell is not in the POSIXly-correct mode and the “long double” floating-point arithmetic is supported on the running system, then “long double” is used for floating-point conversion specifications. Otherwise, “double” is used.

Syntax¶

Description¶

The pushd built-in changes the working directory to directory in the same manner as the cd built-in and adds it to the directory stack. If the working directory could not be changed successfully, the stack is not modified.

Options¶

The pushd built-in accepts the following option as well as the options that can be used for the cd built-in:

--remove-duplicates

Operands¶

directory

Exit status¶

The exit status of the pushd built-in is zero unless there is any error.

Notes¶

The pushd built-in is an elective built-in. It cannot be used in the POSIXly-correct mode because POSIX does not define its behavior.

Syntax¶

Description¶

The pwd built-in prints an absolute path to the shell’s current working directory to the standard output.

Options¶

-L, --logical

-P, --physical

The -L (--logical) and -P (--physical) options are mutually exclusive: only the last specified one is effective. If neither is specified, -L is assumed.

Exit status¶

The exit status of the pwd built-in is zero unless there is any error.

Notes¶

The pwd built-in is a mandatory built-in.

Syntax¶

Description¶

The read built-in reads a line of string from the standard input and assigns it to the specified variables.

If the -r (--raw-mode) option is specified, all characters in the line are treated literally.

If the -r (--raw-mode) option is not specified, backslashes in the line are treated as quotations. If a backslash is at the end of the line, it is treated as a line continuation. When the built-in reads the next line, the PS2 variable is used as a prompt if the shell is interactive and the standard input is a terminal.

The input line is subject to field splitting. The resulting words are assigned to variables in order. If there are more words than variables, the last variable is assigned all the remaining words (as if the words were not split). If the words are fewer than variables, the remaining variables are assigned empty strings.

Options¶

-A, --array

-e, --line-editing

-P, --ps1

-p prompt, --prompt=prompt

-r, --raw-mode

Operands¶

variables

Exit status¶

The exit status of the read built-in is zero unless there is any error.

Note that the exit status is non-zero if an end of input is encountered before reading the entire line.

Notes¶

The read built-in is a mandatory built-in.

The POSIX standard defines the -r option only: other options cannot be used in the POSIXly-correct mode.

The PS1R and PS1S variables affect the behavior of line-editing if the PS1 prompt is used. The same for PS2.

Syntax¶

Description¶

The readonly built-in is equivalent to the typeset built-in with the -gr option.

Notes¶

The readonly built-in is a special built-in.

The POSIX standard defines the -p option only; other options cannot be used in the POSIXly-correct mode. The POSIX does not allow using the option together with operands.

Syntax¶

Description¶

When executed without the -n (--no-return) option, one of the following happens:

When executed with the -n (--no-return) option, the built-in does nothing but return the specified exit_status.

Options¶

-n, --no-return

Operands¶

exit_status

Exit status¶

The exit status of the return built-in is defined by the exit_status operand. The exit status is used also as the exit status of the terminated function, script, or the shell.

Notes¶

The return built-in is a special built-in.

The POSIX standard provides that the exit_status operand should be between 0 and 255 (inclusive). Yash accepts integers larger than 255 as an extension.

In the POSIX standard, the behavior of the return built-in is defined only when the shell is executing a function or script.

The POSIX standard defines no options for the return built-in; the built-in accepts no options in the POSIXly-correct mode.

Syntax¶

The set built-in requires that all options precede operands. Any command line arguments after the first operand are all treated as operands.

Description¶

When executed without any command arguments, the built-in prints a list of all existing variables to the standard input in a form that can be reused as commands that will restore the variable definitions.

When -o is the only command argument, the built-in prints a list of shell options with their current settings. When +o is the only command argument, the built-in prints commands that can be reused to restore the current shell option settings.

In other cases, the built-in changes shell option settings and/or positional parameters.

Options¶

When one or more options are specified, the built-in enables or disables the shell options. A normal hyphen-prefixed option enables a shell option. An option that is prefixed with a plus (+) instead of a hyphen disables a shell option. For example, options -m, -o monitor, and --monitor enable the monitor option and options +m, +o monitor, ++monitor disable it.

The name of a long option is case-insensitive and may include irrelevant non-alphanumeric characters, which are ignored. For example, options --le-comp-debug and --LeCompDebug are equivalent. If no is prepended to the name of a long option, the meaning is reversed. For example, --noallexport is equivalent to ++allexport and ++nonotify to --notify.

An option can be specified in one of the following forms:

Not all options can be specified as single-character options.

The available options are:

all-export (-a)

brace-expand

case-glob

clobber (+C)

cur-async, cur-bg, cur-stop

dot-glob

emacs

empty-last-field

err-exit (-e)

err-return

exec (+n)

extended-glob

for-local

glob (+f)

hash-on-def (-h)

hist-space

ignore-eof

le-always-rp, le-comp-debug, le-conv-meta, le-no-conv-meta, le-predict, le-predict-empty, le-prompt-sp, le-visible-bell, le-trim-right

mark-dirs

monitor (-m)

notify (-b)

notify-le

null-glob

pipe-fail

posixly-correct

trace-all

unset (+u)

verbose (-v)

vi

x-trace (-x)

Operands¶

If one or more operands are passed to the set built-in, current positional parameters are all removed and the operands are set as new positional parameters. If the -- separator (cf. syntax of command arguments) is passed, the positional parameters are set even when there are no operands, in which case new positional parameters will be nothing.

Exit status¶

The exit status of the set built-in is zero unless there is any error.

Notes¶

The set built-in is a special built-in.

In the POSIX standard, available shell options are much limited. The standard does not define:

The options defined in the standard are:

Yash does not support the nolog option, which prevents function definitions from being added to command history.

Syntax¶

Description¶

The shift built-in removes the first count positional parameters or array values, where count is specified by the operand.

Options¶

-A array, --array=array

Operands¶

count

Exit status¶

The exit status of the shift built-in is zero unless there is any error.

Notes¶

The shift built-in is a special built-in.

The number of positional parameters can be obtained with the # special parameter. The number of array values can be obtained with ${array[#]}.

The POSIX standard defines no options for the shift built-in; the built-in accepts no options in the POSIXly-correct mode.

Negative operands are not allowed in the POSIXly-correct mode.

Syntax¶

Description¶

The suspend built-in sends a SIGSTOP signal to all processes in the process group to which the shell process belongs. The signal suspends the processes (including the shell). The suspended processes resume when they receive a SIGCONT signal.

If the shell is interactive and its process group ID is equal to the process ID of the session leader, the shell prints a warning message and refuses to send a signal unless the -f (--force) option is specified. (In such a case, there is no other job-controlling shell that can send a SIGCONT signal to resume the suspended shell, so the shell could never be resumed.)

Options¶

-f, --force

Exit status¶

The exit status is zero if the signal was successfully sent and non-zero otherwise.

Notes¶

The suspend built-in is an elective built-in. It cannot be used in the POSIXly-correct mode because POSIX does not define its behavior.

Syntax¶

The test built-in does not distinguish options and operands; all command line arguments are interpreted as expression. If the built-in is executed with the name [, expression must be followed by ].

Description¶

The test built-in evaluates expression as a conditional expression that is made up of operators and operands described below. The exit status is 0 if the condition is true and 1 otherwise.

The unary operators below test a file. If the operand file is a symbolic link, the file referred to by the link is tested (except for the -h and -L operators).

-b file

-c file

-d file

-e file

-f file

-G file

-g file

-h file

-k file

-L file

-N file

-O file

-p file

-r file

-S file

-s file

-u file

-w file

-x file

The unary operator below tests a file descriptor:

-t fd

The unary operators below test a string:

-n string

-z string

The unary operator below tests a shell option:

-o ?option

-o option

The binary operators below compare files. Non-existing files are considered older than any existing files.

file1 -nt file2

file1 -ot file2

file1 -ef file2

The binary operators below compare strings:

string1 = string2, string1 == string2

string1 != string2

The binary operators below compare strings according to the alphabetic order in the current locale:

string1 === string2

string1 !== string2

string1 < string2

string1 <= string2

string1 > string2

string1 >= string2

The binary operator below performs pattern matching:

string =~ pattern

The binary operators below compare integers:

v1 -eq v2

v1 -ne v2

v1 -gt v2

v1 -ge v2

v1 -lt v2

v1 -le v2

The binary operators below compare version numbers:

v1 -veq v2

v1 -vne v2

v1 -vgt v2

v1 -vge v2

v1 -vlt v2

v1 -vle v2

The operators below can be used to make complex expressions:

! expression

( expression )

expression1 -a expression2