'\" te

.\" Copyright (c) 2008, 2011, Oracle and/or its affiliates. All rights reserved.

.\" Copyright 1989 AT&T

.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved

.\"  Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at  http://www.opengroup.org/bookstore/.

.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.  This notice shall appear on any product containing this material. 

.TH sh 1 "12 Jul 2011" "SunOS 5.11" "User Commands"

.SH NAME

sh, jsh \- standard and job control shell and command interpreter

.SH SYNOPSIS

.LP

.nf

\fB/usr/bin/sh\fR  [\fB-acefhiknprstuvx\fR] [\fIargument\fR]...

.fi

.LP

.nf

\fB/usr/xpg4/bin/sh\fR  [\(+- abCefhikmnoprstuvx]

     [\(+- o \fIoption\fR]... [\fB-c\fR \fIstring\fR] [\fIarg\fR]...

.fi

.LP

.nf

\fB/usr/bin/jsh\fR  [\fB-acefhiknprstuvx\fR] [\fIargument\fR]...

.fi

.SH DESCRIPTION

.sp

.LP

The \fB/usr/bin/sh\fR utility is a command programming language that executes commands read from a terminal or a file.

.sp

.LP

The \fB/usr/xpg4/bin/sh\fR utility is a standards compliant shell. This utility provides all the functionality of \fBksh88\fR(1), except in cases discussed in \fBksh88\fR(1) where differences in behavior exist.

.sp

.LP

The \fBjsh\fR utility is an interface to the shell that provides all of the functionality of \fBsh\fR and enables job control (see \fBJob Control\fR section below).

.sp

.LP

Arguments to the shell are listed in the \fBInvocation\fR section below.

.SS "Definitions"

.sp

.LP

A \fIblank\fR is a tab or a space. A \fIname\fR is a sequence of \fBASCII\fR letters, digits, or underscores, beginning with a letter or an underscore. A \fIparameter\fR is a name, a digit, or any of the characters \fB*\fR, \fB@\fR, \fB#\fR, \fB?\fR, \fB\(mi\fR, \fB$\fR, and \fB!\fR.

.SH USAGE

.SS "Commands"

.sp

.LP

A \fIsimple-command\fR is a sequence of non-blank \fIword\fRs separated by \fIblank\fRs. The first \fIword\fR specifies the name of the command to be executed. Except as specified below, the remaining \fIword\fRs are passed as arguments to the invoked command. The command name is passed as argument 0 (see \fBexec\fR(2)). The \fIvalue\fR of a \fIsimple-command\fR is its exit status if it terminates normally, or (octal) \fB200\fR+\fIstatus\fR if it terminates abnormally. See \fBsignal.h\fR(3HEAD) for a list of status values.

.sp

.LP

A \fIpipeline\fR is a sequence of one or more \fIcommand\fRs separated by \fB|\fR. The standard output of each \fIcommand\fR but the last is connected by a \fBpipe\fR(2) to the standard input of the next \fIcommand\fR. Each \fIcommand\fR is run as a separate process. The shell waits for the last \fIcommand\fR to terminate. The exit status of a \fIpipeline\fR is the exit status of the last command in the \fIpipeline\fR.

.sp

.LP

A \fIlist\fR is a sequence of one or more \fIpipeline\fRs separated by \fB;\fR, \fB&\fR, \fB&&\fR, or \fB|\||\fR, and optionally terminated by \fB;\fR or \fB&\fR\&. Of these four symbols, \fB;\fR and \fB&\fR have equal precedence, which is lower than that of \fB&&\fR and \fB|\||\fR. The symbols \fB&&\fR and \fB|\||\fR also have equal precedence. A semicolon (\fB;\fR) causes sequential execution of the preceding \fIpipeline\fR, that is, the shell waits for the \fIpipeline\fR to finish before executing any commands following the semicolon. An ampersand (\fB&\fR) causes asynchronous execution of the preceding pipeline, that is, the shell does \fBnot\fR wait for that pipeline to finish. The symbol \fB&&\fR (\|\fB|\||\fR) causes the \fIlist\fR following it to be executed only if the preceding pipeline returns a zero (non-zero) exit status. An arbitrary number of newlines can appear in a \fIlist\fR, instead of semicolons, to delimit commands.

.sp

.LP

A \fIcommand\fR is either a \fIsimple-command\fR or one of the following. Unless otherwise stated, the value returned by a command is that of the last \fIsimple-command\fR executed in the command.

.sp

.ne 2

.mk

.na

\fB\fBfor\fR \fIname\fR [ \fBin\fR \fIword\fR .\|.\|. ] \fBdo\fR \fIlist\fR \fBdone\fR\fR

.ad

.sp .6

.RS 4n

Each time a \fBfor\fR command is executed, \fIname\fR is set to the next \fIword\fR taken from the \fBin\fR \fIword\fR list. If \fBin\fR \fIword\fR .\|.\|. is omitted, then the \fBfor\fR command executes the \fBdo\fR \fIlist\fR once for each positional parameter that is set (see \fBParameter Substitution\fR section below). Execution ends when there are no more words in the list.

.RE

.sp

.ne 2

.mk

.na

\fB\fBcase\fR \fIword\fR \fBin\fR [ \fIpattern\fR [ | \fIpattern\fR ] \fB)\fR \fIlist\fR \fB;\|;\fR ] .\|.\|.  \fBesac\fR\fR

.ad

.sp .6

.RS 4n

A \fBcase\fR command executes the \fIlist\fR associated with the first \fIpattern\fR that matches \fIword\fR. The form of the patterns is the same as that used for file-name generation (see \fBFile Name Generation\fR section), except that a slash, a leading dot, or a dot immediately following a slash need not be matched explicitly.

.RE

.sp

.LP

\fBif\fR \fIlist\fR \fB; then\fR \fIlist\fR \fBelif\fR \fIlist\fR \fB; then\fR \fIlist\fR \fB;\fR ] .\|.\|. [ \fBelse\fR \fIlist\fR \fB;\fR ] \fBfi\fR

.sp

.LP

The \fIlist\fR following \fBif\fR is executed and, if it returns a zero exit status, the \fIlist\fR following the first \fBthen\fR is executed. Otherwise, the \fIlist\fR following \fBelif\fR is executed and, if its value is zero, the \fIlist\fR following the next \fBthen\fR is executed. Failing that, the \fBelse\fR \fIlist\fR is executed. If no \fBelse\fR \fIlist\fR or \fBthen\fR \fIlist\fR is executed, then the \fBif\fR command returns a zero exit status.

.sp

.ne 2

.mk

.na

\fB\fBwhile\fR \fIlist\fR \fBdo\fR \fIlist\fR \fBdone\fR\fR

.ad

.RS 27n

.rt  

A \fBwhile\fR command repeatedly executes the \fBwhile\fR \fIlist\fR and, if the exit status of the last command in the list is zero, executes the \fBdo\fR \fIlist\fR; otherwise the loop terminates. If no commands in the \fBdo\fR \fIlist\fR are executed, then the \fBwhile\fR command returns a zero exit status; \fBuntil\fR can be used in place of \fBwhile\fR to negate the loop termination test.

.RE

.sp

.ne 2

.mk

.na

\fB\fB(\fR\fIlist\fR\fB)\fR\fR

.ad

.RS 27n

.rt  

Execute \fIlist\fR in a sub-shell.

.RE

.sp

.ne 2

.mk

.na

\fB\fB{\fR \fIlist\fR\fB;}\fR\fR

.ad

.RS 27n

.rt  

\fIlist\fR is executed in the current (that is, parent) shell. The \fB{\fR must be followed by a space.

.RE

.sp

.ne 2

.mk

.na

\fB\fIname\fR \fB(\|) {\fR \fIlist\fR\fB;}\fR\fR

.ad

.RS 27n

.rt  

Define a function which is referenced by \fIname\fR. The body of the function is the \fIlist\fR of commands between \fB{\fR and \fB}\fR. The \fB{\fR must be followed by a space. Execution of functions is described below (see \fBExecution\fR section). The \fB{\fR and \fB}\fR are unnecessary if the body of the function is a \fIcommand\fR as defined above, under \fBCommands\fR.

.RE

.sp

.LP

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

.sp

.LP

\fBif  then  else  elif  fi  case  esac  for  while  until  do  done  {  }\fR

.SS "Comments Lines"

.sp

.LP

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

.SS "Command Substitution"

.sp

.LP

The shell reads commands from the string between two grave accents (\fB``\fR) and the standard output from these commands can be used as all or part of a word. Trailing newlines from the standard output are removed.

.sp

.LP

No interpretation is done on the string before the string is read, except to remove backslashes (\fB\e\fR) used to escape other characters. Backslashes can be used to escape a grave accent (\fB`\fR) or another backslash (\fB\e\fR) and are removed before the command string is read. Escaping grave accents allows nested command substitution. If the command substitution lies within a pair of double quotes (\fB" .\|.\|.\|` .\|.\|.\|` .\|.\|.\| "\fR), a backslash used to escape a double quote (\fB\e"\fR) is removed. Otherwise, it is left intact.

.sp

.LP

If a backslash is used to escape a newline character (\fB\enewline\fR), both the backslash and the newline are removed (see the later section on \fBQuoting\fR). In addition, backslashes used to escape dollar signs (\fB\e$\fR) are removed. Since no parameter substitution is done on the command string before it is read, inserting a backslash to escape a dollar sign has no effect. Backslashes that precede characters other than \fB\e\fR, \fB`\fR, \fB"\fR, \fBnewline\fR, and \fB$\fR are left intact when the command string is read.

.SS "Parameter Substitution"

.sp

.LP

The character \fB$\fR is used to introduce substitutable \fIparameter\fRs. There are two types of parameters, positional and keyword. If \fIparameter\fR is a digit, it is a positional parameter. Positional parameters can be assigned values by \fBset\fR. Keyword parameters (also known as variables) can be assigned values by writing:

.sp

.LP

\fIname\fR\fB=\fR\fIvalue\fR [ \fIname\fR\fB=\fR\fIvalue\fR ] .\|.\|.

.sp

.LP

Pattern-matching is not performed on \fIvalue\fR. There cannot be a function and a variable with the same \fIname\fR.

.sp

.ne 2

.mk

.na

\fB\fB${\fR\fIparameter\fR\fB}\fR\fR

.ad

.RS 25n

.rt  

The value, if any, of the parameter is substituted. The braces are required only when \fIparameter\fR is followed by a letter, digit, or underscore that is not to be interpreted as part of its name. If \fIparameter\fR is \fB*\fR or \fB@\fR, all the positional parameters, starting with \fB$1\fR, are substituted (separated by spaces). Parameter \fB$0\fR is set from argument zero when the shell is invoked.

.RE

.sp

.ne 2

.mk

.na

\fB\fB${\fR\fIparameter\fR\fB:\(mi\fR\fIword\fR\fB}\fR\fR

.ad

.RS 25n

.rt  

Use Default Values. If \fIparameter\fR is unset or null, the expansion of \fIword\fR is substituted; otherwise, the value of \fIparameter\fR is substituted.

.RE

.sp

.ne 2

.mk

.na

\fB\fB${\fR\fIparameter\fR\fB:=\fR\fIword\fR\fB}\fR\fR

.ad

.RS 25n

.rt  

Assign Default Values. If \fIparameter\fR is unset or null, the expansion of \fIword\fR is assigned to \fIparameter\fR. In all cases, the final value of \fIparameter\fR is substituted. Only variables, not positional parameters or special parameters, can be assigned in this way.

.RE

.sp

.ne 2

.mk

.na

\fB\fB${\fR\fIparameter\fR\fB:?\fR\fIword\fR\fB}\fR\fR

.ad

.RS 25n

.rt  

If \fIparameter\fR is set and is non-null, substitute its value; otherwise, print \fIword\fR and exit from the shell. If \fIword\fR is omitted, the message "parameter null or not set" is printed.

.RE

.sp

.ne 2

.mk

.na

\fB\fB${\fR\fIparameter\fR\fB:+\fR\fIword\fR\fB}\fR\fR

.ad

.RS 25n

.rt  

If \fIparameter\fR is set and is non-null, substitute \fIword\fR; otherwise substitute nothing.

.RE

.sp

.LP

In the above, \fIword\fR is not evaluated unless it is to be used as the substituted string, so that, in the following example, \fBpwd\fR is executed only if \fBd\fR is not set or is null:

.sp

.in +2

.nf

\fBecho  ${d:\(mi`pwd`}\fR

.fi

.in -2

.sp

.sp

.LP

If the colon (\fB:\fR) is omitted from the above expressions, the shell only checks whether \fIparameter\fR is set or not.

.sp

.LP

The following parameters are automatically set by the shell.

.sp

.ne 2

.mk

.na

\fB\fB#\fR\fR

.ad

.RS 8n

.rt  

The number of positional parameters in decimal.

.RE

.sp

.ne 2

.mk

.na

\fB\fB\(mi\fR\fR

.ad

.RS 8n

.rt  

Flags supplied to the shell on invocation or by the \fBset\fR command.

.RE

.sp

.ne 2

.mk

.na

\fB\fB?\fR\fR

.ad

.RS 8n

.rt  

The decimal value returned by the last synchronously executed command.

.RE

.sp

.ne 2

.mk

.na

\fB\fB$\fR\fR

.ad

.RS 8n

.rt  

The process number of this shell.

.RE

.sp

.ne 2

.mk

.na

\fB\fB!\fR\fR

.ad

.RS 8n

.rt  

The process number of the last background command invoked.

.RE

.sp

.LP

The following parameters are used by the shell. The parameters in this section are also referred to as environment variables.

.sp

.ne 2

.mk

.na

\fB\fBHOME\fR\fR

.ad

.RS 13n

.rt  

The default argument (home directory) for the \fBcd\fR command, set to the user's login directory by \fBlogin\fR(1) from the password file (see \fBpasswd\fR(4)).

.RE

.sp

.ne 2

.mk

.na

\fB\fBPATH\fR\fR

.ad

.RS 13n

.rt  

The search path for commands (see \fBExecution\fR section below).

.RE

.sp

.ne 2

.mk

.na

\fB\fBCDPATH\fR\fR

.ad

.RS 13n

.rt  

The search path for the \fBcd\fR command.

.RE

.sp

.ne 2

.mk

.na

\fB\fBMAIL\fR\fR

.ad

.RS 13n

.rt  

If this parameter is set to the name of a mail file \fIand\fR the \fBMAILPATH\fR  parameter is not set, the shell informs the user of the arrival of mail in the specified file.

.RE

.sp

.ne 2

.mk

.na

\fB\fBMAILCHECK\fR\fR

.ad

.RS 13n

.rt  

This parameter specifies how often (in seconds) the shell checks for the arrival of mail in the files specified by the \fBMAILPATH\fR or \fBMAIL\fR parameters. The default value is \fB600\fR seconds (10 minutes). If set to 0, the shell checks before each prompt.

.RE

.sp

.ne 2

.mk

.na

\fB\fBMAILPATH\fR\fR

.ad

.RS 13n

.rt  

A colon-separated list of file names. If this parameter is set, the shell informs the user of the arrival of mail in any of the specified files. Each file name can be followed by % and a message that is e printed when the modification time changes. The default message is, \fByou have mail\fR.

.RE

.sp

.ne 2

.mk

.na

\fB\fBPS1\fR\fR

.ad

.RS 13n

.rt  

Primary prompt string, by default " $ \|".

.RE

.sp

.ne 2

.mk

.na

\fB\fBPS2\fR\fR

.ad

.RS 13n

.rt  

Secondary prompt string, by default " > \|".

.RE

.sp

.ne 2

.mk

.na

\fB\fBIFS\fR\fR

.ad

.RS 13n

.rt  

Internal field separators, normally \fBspace\fR, \fBtab\fR, and \fBnewline\fR (see \fBBlank Interpretation\fR section).

.RE

.sp

.ne 2

.mk

.na

\fB\fBSHACCT\fR\fR

.ad

.RS 13n

.rt  

If this parameter is set to the name of a file writable by the user, the shell writes an accounting record in the file for each shell procedure executed.

.RE

.sp

.ne 2

.mk

.na

\fB\fBSHELL\fR\fR

.ad

.RS 13n

.rt  

When the shell is invoked, it scans the environment (see \fBEnvironment\fR section below) for this name.

.RE

.sp

.LP

See \fBenviron\fR(5) for descriptions of the following environment variables that affect the execution of \fBsh\fR: \fBLC_CTYPE\fR and \fBLC_MESSAGES\fR.

.sp

.LP

The shell gives default values to \fBPATH\fR, \fBPS1\fR, \fBPS2\fR, \fBMAILCHECK\fR, and \fBIFS\fR. Default values for \fBHOME\fR and \fBMAIL\fR are set by \fBlogin\fR(1).

.SS "Blank Interpretation"

.sp

.LP

After parameter and command substitution, the results of substitution are scanned for internal field separator characters (those found in \fBIFS\fR) and split into distinct arguments where such characters are found. Explicit null arguments (\fB""\fR or \fB\&''\fR) are retained. Implicit null arguments (those resulting from \fIparameter\fRs that have no values) are removed.

.SS "Input/Output Redirection"

.sp

.LP

A command's input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a \fIsimple-command\fR or can precede or follow a \fIcommand\fR and are \fBnot\fR passed on as arguments to the invoked command. \fBNote:\fR Parameter and command substitution occurs before \fIword\fR or \fIdigit\fR is used.

.sp

.ne 2

.mk

.na

\fB\fB<\fR\fIword\fR\fR

.ad

.RS 16n

.rt  

Use file \fIword\fR as standard input (file descriptor 0).

.RE

.sp

.ne 2

.mk

.na

\fB\fB>\fR\fIword\fR\fR

.ad

.RS 16n

.rt  

Use file \fIword\fR as standard output (file descriptor 1). If the file does not exist, it is created; otherwise, it is truncated to zero length.

.RE

.sp

.ne 2

.mk

.na

\fB\fB>>\fR\fIword\fR\fR

.ad

.RS 16n

.rt  

Use file \fIword\fR as standard output. If the file exists, output is appended to it by first seeking to the \fBEOF\fR. Otherwise, the file is created.

.RE

.sp

.ne 2

.mk

.na

\fB\fB<\|>\fR\fIword\fR\fR

.ad

.RS 16n

.rt  

Open file \fIword\fR for reading and writing as standard input.

.RE

.sp

.ne 2

.mk

.na

\fB\fB<<\fR[\fB\(mi\fR]\fIword\fR\fR

.ad

.RS 16n

.rt  

After parameter and command substitution is done on \fIword\fR, the shell input is read up to the first line that literally matches the resulting \fIword\fR, or to an \fBEOF\fR. If, however, the hyphen (\fB\(mi\fR) is appended to \fB<<\fR:

.RS +4

.TP

1.

leading tabs are stripped from \fIword\fR before the shell input is read (but after parameter and command substitution is done on \fIword\fR);

.RE

.RS +4

.TP

2.

leading tabs are stripped from the shell input as it is read and before each line is compared with \fIword\fR; and

.RE

.RS +4

.TP

3.

shell input is read up to the first line that literally matches the resulting \fIword\fR, or to an \fBEOF\fR.

.RE

If any character of \fIword\fR is quoted (see \fBQuoting\fR section later), no additional processing is done to the shell input. If no characters of \fIword\fR are quoted:

.RS +4

.TP

1.

parameter and command substitution occurs;

.RE

.RS +4

.TP

2.

(escaped) \fB\enewline\fRs are removed; and

.RE

.RS +4

.TP

3.

\fB\e\fR must be used to quote the characters \fB\e\fR, \fB$\fR, and \fB`\fR.

.RE

The resulting document becomes the standard input.

.RE

.sp

.ne 2

.mk

.na

\fB\fB<&\fR\fIdigit\fR\fR

.ad

.RS 16n

.rt  

Use the file associated with file descriptor \fIdigit\fR as standard input. Similarly for the standard output using \fB>&\fR\fIdigit\fR.

.RE

.sp

.ne 2

.mk

.na

\fB\fB<&\(mi\fR\fR

.ad