sh-posix(1)

Shell Invocation

If the shell is invoked by an exec*() system call and the first character of argument zero (shell parameter 0) is dash (-), the shell is assumed to be a login shell and commands are read first from /etc/profile, then from either .profile in the current directory or $HOME/.profile if either file exists, and finally from the file named by performing parameter substitution on the value of the environment parameter ENV, if the file exists. If the -s option is not present and an arg is, a path search is performed on the first arg to determine the name of the script to execute. When running sh with arg, the script arg must have read permission and any setuid and setgid settings will be ignored. Commands are read as described below.

Shell output, except for the output of some of the commands listed in the Special Commands subsection, is written to standard error (file descriptor 2).

Options

The following options are interpreted by the shell when it is invoked.

The remaining options and operands are described under the set command in the Special Commands subsection.

rsh Restrictions

rsh is used to set up login names and execution environments where capabilities are more controlled than those of the standard shell. The actions of rsh are identical to those of sh, except that the following are forbidden:

The restrictions above are enforced after the .profile and ENV files are interpreted.

When a command to be executed is found to be a shell procedure, rsh invokes sh to execute it. Thus, the end-user is provided with shell procedures accessible to the full power of the standard shell, while being restricted to a limited menu of commands. This scheme assumes that the end-user does not have write and execute permissions in the same directory.

These rules effectively give the writer of the .profile file complete control over user actions, by performing guaranteed set-up actions and leaving the user in an appropriate directory (probably not the login directory).

The system administrator often sets up a directory of commands (usually /usr/rbin) that can be safely invoked by rsh. HP-UX systems provide a restricted editor red (see ed(1)), suitable for restricted users.

Definitions

Commands

A command can be a simple command that executes an executable file, a special command that executes within the shell, or a compound command that provides flow of control for groups of simple, special, and compound commands.

Simple Commands

A simple command is a sequence of blank-separated words that may be preceded by a parameter assignment list. (See the Environment subsection). The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument 0 (see exec(2)). The value of a simple command is its exit status if it terminates normally, or 128+errorstatus if it terminates abnormally (see signal(5) for a list of errorstatus values).

A pipeline is a sequence of one or more commands separated by a bar (|) and optionally preceded by an exclamation mark (!). The standard output of each command but the last is connected by a pipe (see pipe(2)) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. If ! does not precede the pipeline, the exit status of the pipeline is the exit status of the last command in the pipeline. Otherwise, the exit status of the pipeline is the logical negation of the exit status of the last command in the pipeline.

A list is a sequence of one or more pipelines separated by ;, &, &&, or ||, and optionally terminated by ;, &, or |&.

Of these five symbols, ;, &, and |& have equal precedence, which is lower than that of && and ||. The symbols && and || also have equal precedence.

Compound Commands

Unless otherwise stated, the value returned by a compound command is that of the last simple command executed in the compound command. The ; segment separator can be replaced by one or more newlines.

The following keywords are recognized only as the first word of a command and when not quoted:

A compound command is one of the following.

case word in [[;] [(] pattern [| pattern]...) list ;;]... ; esac

for identifier [in word ...] ; do list ; done

if list ; then list ; [elif list ; then list ;]... [else list ;] fi

select identifier [in word ...] ; do list ; done

time pipeline

until list ; do list ; done

while list ; do list ; done

( list )

{ list ; }

[[ expression ]]

Special Commands

Special commands are simple commands that are executed in the shell process. They permit input/output redirection. Unless otherwise indicated, file descriptor 1 (standard output) is the default output location and the exit status, when there are no syntax errors, is zero.

Commands that are marked with "%" are treated specially in the following ways:

Words following commands marked with "&" that are in the format of a variable assignment are expanded with the same rules as a variable assignment. This means that tilde substitution is performed after the = sign and word-splitting and file-name generation are not performed.

% : [arg]...

% . file [arg]...

& alias [-tx] [name[=value]]...

bg [job]...

% break [n]

command [arg]...

% continue [n]

echo [arg]...

% eval [arg]...

% exec [arg]...

% exit [n]

fg [job]...

getopts optstring name [arg]...

jobs [-lnp] [job]...

% newgrp [-] [group]

print [-nprRsu[n]] [arg]...

pwd [-L|-P]

read [-prsu[n]] [name?prompt] [name]...

% return [n]

% shift [n]

test [expr]

% times

% trap [arg] [sig]...

ulimit [-HSacdfnst] [limit]

umask [-S] [mask]

% unset [-fv] name ...

wait [job]

whence [-pv] name ...

Comments

A word beginning with # causes that word and all the following characters up to a newline to be ignored.

Aliasing

The first word of each command is replaced by the text of an alias, if an alias for this word has been defined. An alias name consists of any number of characters excluding metacharacters, quoting characters, file expansion characters, parameter and command substitution characters, and =. The replacement string can contain any valid shell script, including the metacharacters listed above. The first word of each command in the replaced text, other than any that are in the process of being replaced, will be tested for additional aliases. If the last character of the alias value is a blank, the word following the alias is also checked for alias substitution. Aliases can be used to redefine special commands, but cannot be used to redefine the keywords listed in the Compound Commands subsection. Aliases can be created, listed, and exported with the alias command and can be removed with the unalias command. Exported aliases remain in effect for subshells but must be reinitialized for separate invocations of the shell (see the Shell Invocation subsection).

Aliasing is performed when scripts are read, not while they are executed. Therefore, for it to take effect, an alias must be executed before the command referring to the alias is read.

Aliases are frequently used as a shorthand for full path names. An option to the aliasing facility allows the value of the alias to be automatically set to the full path name of the corresponding command. These aliases are called tracked aliases. The value of a tracked alias is defined the first time the identifier is read and becomes undefined each time the PATH variable is reset. These aliases remain tracked so that the next reference will redefine the value. Several tracked aliases are compiled into the shell. The -h option of the set command converts each command name that is an identifier into a tracked alias.

The following exported aliases are compiled into the shell but can be unset or redefined:

Tilde Substitution

After alias substitution is performed, each word is checked to see if it begins with an unquoted tilde (~). If it does, the word up to a / is checked to see if it matches a user name in the /etc/passwd file. If a match is found, the ~ and the matched login name are replaced by the login directory of the matched user. If no match is found, the original text is left unchanged. A ~ alone or before a / is replaced by the value of the HOME parameter. A ~ followed by a + or - is replaced by the value of the parameter PWD and OLDPWD, respectively. In addition, tilde substitution is attempted when the value of a parameter assignment begins with a ~.

Command Substitution

The standard output from a command enclosed in parenthesis preceded by a dollar sign ($(...)) or a pair of grave accents (`...`) can be used as part or all of a word; trailing newlines are removed. In the second (archaic) form, the string between the accents is processed for special quoting characters before the command is executed. See the Quoting subsection. The command substitution $(cat file) can be replaced by the equivalent but faster $(<file). Command substitution of most special commands that do not perform input/output redirection are carried out without creating a separate process.

An arithmetic expression enclosed in double parenthesis preceded by a dollar sign ($((...))) is replaced by the value of the arithmetic expression within the double parenthesis. See the Arithmetic Evaluation subsection for a description of arithmetic expressions.

Parameter Substitution

A parameter is an identifier, one or more decimal digits, or one of the characters !, #, $, *, -, ?, @, and _. A named parameter (a parameter denoted by an identifier) has a value and zero or more attributes. Named parameters can be assigned values and attributes with the typeset special command. Exported parameters pass values and attributes to the environment.

The shell supports a limited one-dimensional array facility. An element of an array parameter is referenced by a subscript. A subscript is denoted by a [, followed by an arithmetic expression, followed by a ]. See the Arithmetic Evaluation subsection. To assign values to an array, use set -A name value .... The value of all subscripts must be in the range of 0 through 1023. Arrays need not be declared. Any reference to a named parameter with a valid subscript is legal and an array is created if necessary. Referencing an array parameter without a subscript is equivalent to referencing the first element.

If the -i integer attribute is set for name, the value is subject to arithmetic evaluation.

Positional parameters, parameters denoted by a number, can be assigned values with the set special command. Parameter 0 is set from argument zero when the shell is invoked.

Use the prefix character $ to specify the value of a parameter for substitution.

In the above, word is not evaluated unless it is used as the substituted string. Thus, in the following example, pwd is executed only if d is not set or is null:

If the colon (:) is omitted from the above expressions, the shell only checks to determine whether or not parameter is set.

• The following parameters are set automatically by the shell:

• The following parameters are used by the shell:

The shell gives default values to IFS, MAILCHECK, PATH, PS1, PS2, and TMOUT. On the other hand, MAIL, ENV, HOME, and SHELL are never set automatically by the shell (although HOME, MAIL, and SHELL are set by login; see login(1)).

Blank Interpretation

After parameter and command substitution, the results of substitution are scanned for field separator characters (defined in IFS), and split into distinct arguments when such characters are found. sh retains explicit null arguments ("" or '') but removes implicit null arguments (those resulting from parameters that have null values).

File Name Generation

Following substitution, each command word is processed as a pattern for file name expansion unless expansion has been disabled with the set -f special command. The form of the patterns is the Pattern Matching Notation defined in regexp(5). The word is replaced with sorted file names matching the pattern. If no file name is found that matches the pattern, the word is left unchanged.

In addition to the notation described in regexp(5), sh recognizes composite patterns made up of one or more patterns separated from each other with a |. Composite patterns can be formed with one or more of the following:

Quoting

Each of the metacharacters (see the Definitions subsection) has a special meaning to the shell and terminates a word unless quoted. A character may be quoted (that is, made to stand for itself) by preceding it with a backslash (\). The pair \newline is ignored; the current and following lines are concatenated.

All characters enclosed between a pair of apostrophes ('...') are quoted. An apostrophe cannot appear within apostrophes.

Parameter and command substitution occurs inside quotation marks (" ..." ). \ quotes the characters \, `, " , and $.

Inside grave accent marks (`...`), \ quotes the characters \, `, and $. If the grave accents occur within quotation marks, \ also quotes the character " .

The meanings of $* and $@ are identical when not quoted or when used as a parameter assignment value or as a file name. However, when used as a command argument, " $* " is equivalent to " $1d$2d..." , whereas " $@ " is equivalent to " $1 " d " $2 " d... (where d is the first character of IFS),

The special meaning of keywords or aliases can be removed by quoting any character of the name. The recognition of function names or special command names cannot be altered by quoting them.

Arithmetic Evaluation

Integer arithmetic is provided with the special command let. Evaluations are performed using long integer arithmetic. Constants take the form base#n or n, where base is a decimal number between two and thirty-six representing the arithmetic base and n is a number in that base. If base# is omitted, base 10 is used.

An arithmetic expression uses the same syntax, precedence, and associativity of expression as the C language. All the integral operators, other than ++, --, ?:, and , are supported. Variables can be referenced by name within an arithmetic expression without using the parameter substitution syntax. When a variable is referenced, its value is evaluated as an arithmetic expression.

A variable can be typed as an integer with the -i option of the typeset special command, as in typeset -i[base] name. Arithmetic evaluation is performed on the value of each assignment to a variable with the -i attribute. If you do not specify an arithmetic base, the first assignment to the variable determines the arithmetic base. This base is used when parameter substitution occurs.

Since many of the arithmetic operators require quoting, an alternative form of the let command is provided. For any command beginning with ((, all characters until the matching )) are treated as a quoted expression. More precisely, ((...)) is equivalent to let " ..." .

Arithmetic expressions given with let command, ((...)), and $((...)) will be processed according to ISOC standard with the exception of ++, --, ?:, and , operators.

Prompting

When used interactively, the shell prompts with the value of PS1 before reading a command. Whenever a newline is received and further input is needed to complete a command, the secondary prompt (the value of PS2) is issued.

Conditional Expressions

A conditional expression is used with the [[ compound command to test attributes of files and to compare strings. Word splitting and file name generation are not performed on the words between [[ and ]]. (See also the test special command.) Each expression can be constructed from one or more of the following unary or binary expressions:

A compound expression can be constructed from these primitives by using any of the following, listed in decreasing order of precedence.

Input/Output

Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or may precede or follow a command and are not passed on to the invoked command. Command and parameter substitution occurs before word or digit is used, except as noted below. File name generation occurs only if the pattern matches a single file and blank interpretation is not performed.

If any of the above redirections is preceded by a digit (0 to 9), the file descriptor used is the one specified by the digit, instead of the default 0 (standard input) or 1 (standard output). For example:

means open file descriptor 2 for writing as a duplicate of file descriptor 1. Output directed to file descriptor 2 is written in the same location as output to file descriptor 1.

Order is significant in redirection. The shell evaluates each redirection in terms of the (file descriptor, file) assignment at the time of evaluation. For example:

first assigns file descriptor 1 to file fname. It then assigns file descriptor 2 to the file assigned to file descriptor 1 (that is, fname).

If the order of redirection is reversed, as in

file descriptor 2 is assigned to the file assigned to file descriptor 1 (probably the terminal) and then file descriptor 1 is assigned to file fname.

By using the redirection operators above, the input and output of a coprocess may be moved to a numbered file descriptor, allowing other commands to write to them and read from them. If the input of the current coprocess is moved to a numbered file descriptor, another coprocess may be started.

If a command is followed by & and job control is inactive, the default standard input for the command is the empty file /dev/null. Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications.

Environment

The environment (see environ(5)) is a list of name-value pairs passed to an executed program much like a normal argument list. The names must be identifiers and the values are character strings. The shell interacts with the environment in several ways. When invoked, the shell scans the environment and creates a parameter for each name found, gives it the corresponding value and marks it export. Executed commands inherit the environment. If the user modifies the values of these parameters or creates new ones by using the export or typeset -x special commands, the values become part of the environment. The environment seen by any executed command is thus composed of any name-value pairs originally inherited by the shell, whose values may be modified by the current shell, plus any additions which must be noted in export or typeset -x commands.

The environment for any simple command or function can be augmented by prefixing it with one or more parameter assignments. A parameter assignment argument takes the form identifier=value. For example, both the following

are equivalent (as far as the execution of cmd is concerned, except for the special commands that are preceded by a percent sign (%).

If the -k option is set, all parameter assignment arguments are placed in the environment, even if they occur after the command name. The following echo statement prints a=b c. After the -k option is set, the second echo statement prints only c:

This feature is intended for use with scripts written for early versions of the shell and its use in new scripts is strongly discouraged. It is likely to disappear someday.

Functions

The function command (described in the Compound Commands subsection) defines shell functions. Shell functions are read and stored internally. Alias names are resolved when the function is read. Functions are executed like commands, with the arguments passed as positional parameters. (See the Execution subsection.)

Functions execute in the same process as the caller and share all files and current working directory with the caller. Traps defined by the caller remain in effect within the function until another trap command is executed. Traps set within a function remain in effect after the function returns. Ordinarily, variables are shared between the calling program and the function. However, the typeset special command can be used within a function to define local variables whose scope includes the current function and all functions it calls.

The return special command is used to return from function calls. Errors within functions return control to the caller.

Function identifiers can be listed with the +f option of the typeset special command. Function identifiers and the associated text of the functions can be listed with the -f option. Functions can be undefined with the -f option of the unset special command.

Ordinarily, functions are unset when the shell executes a shell script. The -xf option of the typeset command allows a function to be exported to scripts that are executed without reinvoking the shell. Functions that must be defined across separate invocations of the shell should be placed in the ENV file.

Jobs

If the monitor option of the set command is turned on, an interactive shell associates a job with each pipeline. It keeps a table of current jobs, printed by the jobs command, and assigns them small integer numbers. When a job is started asynchronously with &, the shell prints a line that looks like:

indicating that job number 1 was started asynchronously and had one (top-level) process whose process ID was 1234.

If you are running a job and wish to do something else, you can type the suspend character (the susp character defined with stty; see stty(1)) to send a SIGSTOP signal to the current job. The shell then indicates that the job has been Stopped, and prints another prompt. Then you can manipulate the state of this job by putting it in the background with the bg command, running other commands, and eventually returning the job to the foreground with the fg command. A suspend takes effect immediately and resembles an interrupt, since pending output and unread input are discarded when the suspend is entered.

A job running in the background stops if it tries to read from the terminal. Background jobs normally are allowed to produce output, but can be disabled with the stty tostop command. If the user sets this terminal option, background jobs stop when trying to produce output.

There are several ways to refer to jobs in the shell. A job can be referred to by the process ID of any process in the job or by one of the following:

The shell learns immediately when a process changes state. It informs the user when a job is blocked and prevented from further progress, but only just before it prints a prompt.

When the monitor mode is on, each background job that completes triggers any trap set for SIGCHLD.

If you try to exit from shell while jobs are stopped, you are warned with the message You have stopped jobs. You can use the jobs command to identify them. If you immediately try to exit again, the shell will not warn you a second time, and the stopped jobs will be terminated.

If you try to leave the shell while jobs are running, you are not warned. The shell exits silently and sets the parent of the running jobs to the init process (number 1).

Signals

The SIGINT and SIGQUIT signals for an invoked command are ignored if the command is followed by & and the monitor option is off. Otherwise, signals have the values inherited by the shell from its parent, with the exception of signal SIGSEGV (but see also the trap special command).

Execution

Substitutions are made each time a command is executed. sh checks the command name to determine whether it matches a special command. If it does, it is executed within the current shell process.

Next, sh checks the command name to determine whether it matches one of the user-defined functions. If it does, sh saves the positional parameters, then sets them to the arguments of the function call. The positional parameter 0 is unchanged. When the function completes or issues a return, sh restores the positional parameter list. The value of a function is the value of the last command executed. A function is executed in the current shell process.

If a command name is not a user-defined function or a special command, sh creates a process and attempts to execute the command using an exec*() system call (see exec(2)).

The shell parameter PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon (:). The default path is /usr/bin: (specifying /usr/bin, and the current directory, in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign, between colon delimiters, or at the end of the path list. The search path is not used if the command name contains a /. Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file, which is a file of data for an interpreter. If the first two characters of the script file are #!, exec*() expects an interpreter path name to follow. exec*() then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to exec*() fails, sh is spawned to interpret the script file. All nonexported aliases, functions, and named parameters are removed in this case. If the shell command file does not have read permission, or if the setuid and/or setgid bits are set on the file, the shell executes an agent to set up the permissions and execute the shell with the shell command file passed down as an open file. A parenthesized command is also executed in a subshell without removing nonexported quantities.

Command Reentry

The text of the last HISTSIZE (default 128) commands entered from a terminal device is saved in a history file. The file $HOME/.sh_history is used if the HISTFILE variable is not set or writable. A shell can access the commands of all interactive shells that use the same named HISTFILE. The special command fc is used to list or edit a portion of this file. The portion of the file to be edited or listed can be selected by number or by giving the first character or characters of the command. A single command or range of commands can be specified. If you do not specify an editor program as an argument to fc, the value of the parameter FCEDIT is used. If FCEDIT is not defined, /usr/bin/ed is used. The edited command is printed and reexecuted upon leaving the editor. The editor name - is used to skip the editing phase and to reexecute the command. In this case, a substitution parameter of the form old=new can be used to modify the command before execution. For example, if r is aliased to fc -e -, typing r bad=good c reexecutes the most recent command that starts with the letter c and replaces the first occurrence of the string bad with the string good.

The history file will be trimmed when all of the following conditions occurs:

If any one of the above conditions does not occur, the history file will not be trimmed. When the history file is trimmed, the latest HISTSIZE commands will be available in the history file.

Command Line Editing

Normally, each command line typed at a terminal device is followed by a newline or return. If one of the emacs, gmacs, vi, or viraw, options is set, you can edit the command line. An editing option is automatically selected each time the VISUAL or EDITOR variable is assigned a value ending in one of these option names.

The editing features require that the user's terminal accept return without line feed and that a space (" ") must overwrite the current character on the screen. ADM terminal users should set the "space - advance" switch to "space". Hewlett-Packard terminal users should set the straps to "bcGHxZ etX".

The editing modes enable the user to look through a window at the current line. The default window width is 80, unless the value of COLUMNS is defined. If the line is longer than the window width minus two, a mark displayed at the end of the window notifies the user. The mark is one of:

As the cursor moves and reaches the window boundaries, the window is centered about the cursor.

The search commands in each edit mode provide access to the history file. Only strings are matched, not patterns, although a leading ^ in the string restricts the match to begin at the first character in the line.

Changing the LC_TYPE environment variable can affect the editors. See the Parameter Substitution subsection.

emacs/gmacs Editing Mode

This mode is invoked by either the emacs or gmacs option. The sole difference is how they handle Control-T.

To edit, the user moves the cursor to the point needing correction and inserts or deletes characters or words. All editing commands are control characters or escape sequences. The notation for control characters is caret (^) followed by a character. For example, ^F is the notation for Control-F. This is entered by holding down the Ctrl (control) key and pressing f. The shift key is not pressed. The notation ^? indicates the delete (DEL) key.

The notation for escape sequences is M- followed by a character. For example, M-f (pronounced meta f) is entered by pressing the escape key (Esc) followed by pressing f. M-F is the notation for escape followed by shift (capital) F.

All edit commands operate from any place on the line (not only at the beginning). Neither the return (^M) nor the newline (^J) key is entered after edit commands, except when noted.

vi Editing Mode

The editor starts in insert mode until an escape (ESC) is received. This puts you in control mode in which you can move the cursor and perform editing commands. A return in either mode sends the line.

Most control commands accept an optional repeat count prior to the command.

In vi mode on most systems, canonical processing is initially enabled and the command is echoed again if the speed is 1200 baud or greater and contains any control characters, or if less than one second has elapsed since the prompt was printed. The escape (ESC) character terminates canonical processing for the remainder of the command and you can then modify the command line. This scheme has the advantages of canonical processing with the typeahead echoing of raw mode.

Setting the viraw option always disables canonical processing on the terminal. This mode is implicit for systems that do not support two alternate end-of-line delimiters, and may be helpful for certain terminals.

Environment Variables

LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. If it is not defined or is empty, it defaults to the value of LANG.

LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. If it is not defined or is empty, it defaults to the value of LANG.

If LANG is not defined or is empty, it defaults to C (see lang(5)).

If any internationalization variable contains an invalid value, they all default to C (see environ(5)).

International Code Set Support

Single- and multibyte character code sets are supported.

Collating Order

In an international environment, character ordering is determined by the value of LC_COLLATE, rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command,

might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by LC_COLLATE, it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after z in languages such as Danish or Norwegian.

The correct (and safe) way to match specific character classes in an international environment is to use a pattern (see regexp(5)) of the form:

This uses LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on noninternationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-NLS environment. This requires that LANG, LC_COLLATE, and so on, be set to C or not set at all.

History File and Locales

The history file does not support mixing of locales in the same file. For users of multiple locales, you can assign a unique history file for each locale by setting HISTFILE as:

On encountering a history file with invalid characters for the current locale setting, the shell will inform the user about it and continue processing user input. No history features will be available to the user in such a session. Restarting the shell after setting a new history file or after removing the current history file allows the user to access the history features.

Here-Document Temp Files

The contents of here-documents are stored in temporary files named /var/tmp/shpid.number. Usually, these temporary files are removed after they are used. However, due to design limitations, these temporary files may sometimes continue to exist after the shell exits. pid is the process ID of the shell. number is a sequence number for the here-document files.