Description: This page describes common properties of built-ins of yash.

# Built-in commands

Built-in commands are commands that are implemented in the shell and are executed by the shell without starting external programs.

See the table of contents for the list of the built-ins.

## 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 1. 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.

- `set -o errexit -m`

- `set -oerrexit -m`

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 2. 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.

- `fc --editor vi --quiet`

- `fc --editor=vi --quiet`

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 3. Options and operands to the set built-in

- `set -a -b -- -c -d`

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.