[0m


SH(1)		    UNIX Programmer's Manual		    SH(1)



[1mNAME
     [0msh, for, case, if, while, [1m:[0m, [1m.[0m, break, continue, cd, echo,
     eval, exec, exit, export, hash, login, pwd, read, readonly,
     return, set, shift, test, times, trap, type, ulimit, umask,
     unset, wait - command language

[1mSYNOPSIS
     sh [0m[ [1m-abcefhiknrstuvx [0m| [1m-- [0m] [ [1m+abcefhiknrstuvx [0m] [ arg ]
     ...
     [1mrsh [0m[ _f_l_a_g_s ] [ _a_r_g_u_m_e_n_t_s ]

[1mDESCRIPTION
     [0m_S_h is a command programming language that executes commands
     read from a terminal or a file.  See "[1mInvocation[0m" for the
     meaning of arguments to the shell.  _S_h is the recommended
     interface for writing "command scripts" and is a fairly
     widely available interactive interface.  Unlike _c_s_h(1) _s_h
     does not provide job control facilities to manage simultane-
     ous execution of multiple commands.

     [1mCommands

     [0mA _s_i_m_p_l_e _c_o_m_m_a_n_d is a sequence of non blank _w_o_r_d_s separated
     by blanks (a blank is a [1mtab [0mor a [1mspace[0m).  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 argu-
     ment 0 (see _e_x_e_c_v_e(2)).  The _v_a_l_u_e of a _s_i_m_p_l_e _c_o_m_m_a_n_d is
     its exit status if it terminates normally or _s_t_a_t_u_s+128 (200
     octal) if it terminates abnormally.  In this case the _s_t_a_t_u_s
     is the number of the signal which caused the termination -
     see _s_i_g_v_e_c(2) for a list of signal values.  Exit status
     values are determined by the individual command, the only
     firm rule being that zero means success.

     A _p_i_p_e_l_i_n_e is a sequence of one or more _c_o_m_m_a_n_d_s separated
     by [1m|[0m.  The standard output of each command but the last is
     connected by a _p_i_p_e(2) to the standard input of the next
     command.  Each command is run as a separate process, all the
     commands run concurrently; the shell waits for the last com-
     mand to terminate.  The exit status of the pipeline is the
     exit status of the last command in the pipeline.

     A _l_i_s_t is a sequence of one or more _p_i_p_e_l_i_n_e_s separated by
     [1m;[0m, [1m&[0m, [1m&& [0mor [1m|| [0mand optionally terminated by [1m; [0mor [1m&[0m.  Within
     this group of four symbols [1m; [0mand [1m& [0mhave equal precedence
     which is lower than that of [1m&& [0mand [1m||[0m.  [1m&& [0mand [1m|| [0malso have
     equal precedence.	A semicolon causes sequential execution
     (left to right); an ampersand causes the preceding _p_i_p_e_l_i_n_e
     to be executed without waiting for it to finish.  The sym-
     bols [1m&& [0mand [1m|| [0malso cause sequential execution, however the
     _l_i_s_t following one of these symbols is only executed if the



Printed 22/5/92     Revision 1.6 of 22/10/90			1






SH(1)		    UNIX Programmer's Manual		    SH(1)



     preceding _p_i_p_e_l_i_n_e returns a zero ([1m&&[0m) or non-zero ([1m||[0m)
     value.  Newlines may appear in a _l_i_s_t, instead of semi-
     colons, to delimit commands.

     A _c_o_m_m_a_n_d is either a _s_i_m_p_l_e _c_o_m_m_a_n_d or one of the follow-
     ing.  The value returned by a command is that of the last
     _s_i_m_p_l_e _c_o_m_m_a_n_d executed in the command.

     [1mfor [0m_n_a_m_e [[1min [0m_w_o_r_d ...] [1mdo [0m_l_i_s_t [1mdone
	  [0mEach time a [1mfor [0mcommand is executed _n_a_m_e is set to the
	  next word in the [1mfor [0mword list.  If [1min [0m_w_o_r_d ...  is
	  omitted, [1min $@ [0mis assumed.  Execution ends when there
	  are no more words in the list.

     [1mcase [0m_w_o_r_d [1min [0m[_p_a_t_t_e_r_n [ [1m| [0m_p_a_t_t_e_r_n ] ... [1m) [0m_l_i_s_t [1m;;[0m] ... [1mesac
	  [0mA [1mcase [0mcommand executes the _l_i_s_t associated with the
	  first pattern that matches _w_o_r_d. The form of the pat-
	  terns is the same as that used for file name generation
	  except that no special interpretation is place on [1m/ [0mor
	  [1m/. [0mso these may be matched by [1m* [0mor [1m? [0min the pattern.

     [1mif [0m_l_i_s_t [1mthen [0m_l_i_s_t [[1melif [0m_l_i_s_t [1mthen [0m_l_i_s_t] ... [[1melse [0m_l_i_s_t] [1mfi
	  [0mThe _l_i_s_t following [1mif [0m(the test) is executed and if it
	  returns zero the _l_i_s_t following [1mthen [0mis executed.  Oth-
	  erwise, the _l_i_s_t following [1melif [0mis executed and if its
	  value is zero the _l_i_s_t following [1mthen [0mis executed.
	  Failing that the [1melse [0m_l_i_s_t is executed.  If the test
	  fails but no [1melse [0mclause is present the [1mif [0mcommands
	  returns a zero exit status, however this is not port-
	  able.  The effect of the [1m-e [0mflag (see the [1mset [0mcommand
	  below) is suspended while the test is executed, again,
	  this is not portable.

     [1mwhile [0m_l_i_s_t [[1mdo [0m_l_i_s_t] [1mdone
	  [0mA [1mwhile [0mcommand repeatedly executes the [1mwhile [0m_l_i_s_t and
	  if its value is zero executes the [1mdo [0m_l_i_s_t; otherwise
	  the loop terminates.	The value returned by a [1mwhile
	  [0mcommand is that of the last executed command in the [1mdo
	  [0m_l_i_s_t.  [1muntil [0mmay be used in place of [1mwhile [0mto negate
	  the loop termination test.  As with [1mif [0mthe [1m-e [0mflag is
	  ignored during the test.  If no commands are executed
	  the [1mwhile [0mcommand returns a 0 exit status.

     [1m( [0m_l_i_s_t [1m)
	  [0mExecute _l_i_s_t in a subshell.

     [1m{ [0m_l_i_s_t [1m;}
	  [0m_l_i_s_t is simply executed.  The [1m; [0mmust not be omitted,
	  but it can be replaced by a newline.	(The [1m} [0mmust be
	  parsed by the shell as a command.)

     _n_a_m_e[1m() [0m_c_o_m_m_a_n_d



Printed 22/5/92     Revision 1.6 of 22/10/90			2






SH(1)		    UNIX Programmer's Manual		    SH(1)



	  This defines a built-in command called _n_a_m_e; such com-
	  mands are called _f_u_n_c_t_i_o_n_s.  The existing built-in com-
	  mands cannot be redefined (this is enforced silently by
	  executing the built-in command in preference to the
	  function).  The new function can be used anywhere a
	  simple command may appear.  When it is executed the
	  body of the function defined by _c_o_m_m_a_n_d is executed
	  with the positional parameters [1m$[0m_n set to the arguments
	  of the function - see the "[1mExecution[0m" section below.
	  _C_o_m_m_a_n_d will normally not be one of the above forms,
	  rather than just a _s_i_m_p_l_e _c_o_m_m_a_n_d. Frequently the form:

	  [1m{ [0m_l_i_s_t [1m;}

	  [0mis used to allow a sequence of _c_o_m_m_a_n_d_s to be executed.

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

	  [1mif then else elif fi case in esac for while until do
	  done { }

     Comments

     [0mComments may be included in the input to the shell using the
     [1m# [0mcharacter at the start of a word.  The word and all fol-
     lowing words to the end of the line are ignored by the
     shell.  The end of the line is recognised even if escaped
     using [1m\[0m.

     [1mCommand substitution

     [0mThe standard output from a command enclosed in a pair of
     back quotes ([1m``[0m) (the ISO-8859 grave accent character) may
     be used as part or all of a word or as a series of words;
     trailing newlines are removed, embedded newlines are treated
     as space characters (although they remain as newline charac-
     ters if quoted within a word).  This is because the shell
     separates the input into words after performing the substi-
     tution.

     [1mParameter substitution

     [0mThe character [1m$ [0mis used to introduce substitutable parame-
     ters, either positional parameters or keyword parameters,
     known as _v_a_r_i_a_b_l_e_s.  Positional parameters may be assigned
     values by [1mset [0mand have names which are single digits ([1m0[0m-[1m9[0m).
     The initial value of the positional parameters is defined by
     the successive words of the command which invoked the shell
     or function, with [1m$0 [0mbeing the shell or function name.
     Variables may be set and created by writing




Printed 22/5/92     Revision 1.6 of 22/10/90			3






SH(1)		    UNIX Programmer's Manual		    SH(1)



	  _n_a_m_e[1m=[0m_v_a_l_u_e [ _n_a_m_e[1m=[0m_v_a_l_u_e ] ...

     The [1m= [0mmust immediately follow the _n_a_m_e; they must be part of
     the same word.  The _v_a_l_u_e is not scanned for pattern match-
     ing characters [1m* [0mor [1m?[0m.

     Variable and function names occupy the same name space - a
     name cannot be used for both a variable and a function at
     the same time (creating a variable of a given name will des-
     troy the function and vice versa).

     Parameter substitution is performed according to the format
     of the substitutable parameter, a _p_a_r_a_m_e_t_e_r is a sequence of
     ASCII letters, digits or underscores (a _n_a_m_e), a digit, or
     any of the characters [1m* @ # ? - $ !.  [0mNotice that characters
     in the upper half of the ISO-8859 character set, although
     they may correspond to alphabetic characters, are not sup-
     ported within _n_a_m_e_s.

     [1m${[0m_p_a_r_a_m_e_t_e_r[1m}
	  [0mThe value, if any, of the parameter is substituted.
	  The braces are required only when _p_a_r_a_m_e_t_e_r is followed
	  by a letter, digit, or underscore that is not to be
	  interpreted as part of its name.  If _p_a_r_a_m_e_t_e_r is a
	  digit, it is a positional parameter.	If _p_a_r_a_m_e_t_e_r is [1m*
	  [0mor [1m@ [0mthen all the positional parameters, starting with
	  [1m$1[0m, are substituted separated by spaces.  [1m$0 [0mis set
	  from argument zero when the shell is invoked.

     [1m${[0m_p_a_r_a_m_e_t_e_r[1m:-[0m_w_o_r_d[1m}
	  [0mIf _p_a_r_a_m_e_t_e_r is set and is not the empty string, sub-
	  stitute its value; otherwise substitute _w_o_r_d.

     [1m${[0m_p_a_r_a_m_e_t_e_r[1m:=[0m_w_o_r_d[1m}
	  [0mIf _p_a_r_a_m_e_t_e_r is not set or is the empty string, set it
	  to _w_o_r_d; the value of the parameter is then substi-
	  tuted.  Positional parameters may not be set in this
	  way.

     [1m${[0m_p_a_r_a_m_e_t_e_r[1m:?[0m_w_o_r_d[1m}
	  [0mIf _p_a_r_a_m_e_t_e_r is set and is not the empty string, sub-
	  stitute its value; otherwise, print _w_o_r_d and exit from
	  the shell or, for an interactive shell, return control
	  to the user.	If _w_o_r_d is omitted the standard message:

	  _p_a_r_a_m_e_t_e_r[1m: parameter null or not set

	  [0mis printed.

     [1m${[0m_p_a_r_a_m_e_t_e_r[1m:+[0m_w_o_r_d[1m}
	  [0mIf _p_a_r_a_m_e_t_e_r is set and is not the empty string, sub-
	  stitute _w_o_r_d; otherwise substitute nothing.



Printed 22/5/92     Revision 1.6 of 22/10/90			4






SH(1)		    UNIX Programmer's Manual		    SH(1)



     In the above _w_o_r_d is not evaluated unless it is to be used
     as the substituted string.  (So that, for example, "echo
     ${d-'pwd'}" will only execute _p_w_d if _d is unset.)

     The colon may be omitted from the above forms in which case
     the shell does not check a set parameter to ensure that it
     is not set to the empty string.

     The following parameters are automatically set by the shell:

	  [1m#    [0mThe number of positional parameters in decimal.
	  [1m-    [0mOptions supplied to the shell on invocation or by
	       [1mset[0m.  The options are a list of lower case latters
	       (see the [1mset [0mcommand below).  There is no leading
	       [1m-[0m.
	  [1m?    [0mThe value returned by the last executed command in
	       decimal.  This is not set as a result of back-
	       ground commands (run with a trailing [1m&[0m) terminat-
	       ing.
	  [1m$    [0mThe process number of this shell.
	  [1m!    [0mThe process number of the last background command
	       invoked.

     The following _p_a_r_a_m_e_t_e_r_s are used but not set by the shell.

	  [1mHOME	    [0mThe default argument (home directory) for the
		    [1mcd [0mcommand.
	  [1mPATH	    [0mThe search path for commands (see the "[1mExecu-
		    tion[0m" subsection).	This may not be changed
		    if the shell is running with the [1m-r [0moption.
	  [1mCDPATH    [0mThe search path for the [1mcd [0mcommand - see the
		    "[1mSpecial Commands[0m" subsection.
	  [1mMAIL	    [0mIf this variable is set to the name of a mail
		    file and the [1mMAILPATH [0mvariable is not set,
		    the shell informs the user of the arrival of
		    mail in the specified file.  This is done by
		    checking the length of the file at intervals
		    specified by [1mMAILCHECK[0m, so the facility can
		    be used to detect length increase of any
		    file.  The check is only performed for
		    interactive shells.
	  [1mMAILCHECK [0mThis variable gives the delay in seconds
		    between each check on the files specified by
		    [1mMAIL [0mor [1mMAILPATH[0m.  The default value (if the
		    variable is not set) is 600 seconds.  If the
		    variable is set to 0 the shell will check
		    before each primary prompt is displayed.
	  [1mMAILPATH  [0mThis variable may be set to a colon separated
		    list of file names.  If set an interactive
		    shell will check all of these files at inter-
		    vals specified by [1mMAILCHECK [0mand inform the
		    user if the length of any increases.  If the



Printed 22/5/92     Revision 1.6 of 22/10/90			5






SH(1)		    UNIX Programmer's Manual		    SH(1)



		    file name is followed by a [1m% [0mcharacter then a
		    message that message will be printed if the
		    file length increases, otherwise the default
		    message "[1myou have mail[0m" will be printed.
	  [1mPS1	    [0mPrimary prompt string, by default '$ '.
	  [1mPS2	    [0mSecondary prompt string, by default '> '.
	  [1mIFS	    [0mInternal field separators, normally [1mspace[0m,
		    [1mtab[0m, and [1mnewline[0m.
	  [1mSHELL     [0mNormally this variable holds the name of the
		    shell to use for interactive commands.  When
		    _s_h starts it scans its environment for this
		    name, if the name exists and its filename
		    part contains an "r" character the shell
		    becomes a restricted shell, as though the [1m-r
		    [0moption was specified on the command line -
		    see the "[1mInvocation[0m" subsection below.

     Notice that this implementation of the shell does not use
     the facilities of the native language system, in particular
     the variables [1mLANG[0m,[1mLC_* [0mand [1mNLSPATH [0mare not handled.

     [1mBlank interpretation

     [0mAfter parameter and command substitution, any results of
     substitution are scanned for internal field separator char-
     acters (those found in [1m$IFS[0m) and split into distinct argu-
     ments where such characters are found.  As a result explicit
     null arguments ("" or '') are retained whereas the results
     of parameter substitutions are indistinguishable from the
     indentical characters typed directly into the command line -
     in particular if a parameter substitution results in inser-
     tion of no characters the preceding and following characters
     appear immediately adjacent.

     [1mFile name generation

     [0mFollowing substitution, each command word is scanned for the
     characters [1m*[0m, [1m? [0mand [1m[[0m.  If one of these characters appears,
     the word is regarded as a pattern.  The word is replaced
     with sorted file names that match the pattern.  If no file
     name is found that matches the pattern, the word is left
     unchanged.  The character [1m. [0mat the start of a file name or
     immediately following a [1m/[0m, and the character [1m/[0m, must be
     matched explicitly.  The order into which the names are
     sorted is determined by the ASCII value of the corresponding
     characters.  Byte values in the range 128-255 are sign
     extended to give the corresponding negative values (this is
     not portable).

     [1m*	  [0mMatches any string, including the null string.
     [1m?	  [0mMatches any single character.
     [1m[...]



[0mPrinted 22/5/92     Revision 1.6 of 22/10/90			6






SH(1)		    UNIX Programmer's Manual		    SH(1)



	  Matches any one of the characters enclosed.  A pair of
	  characters separated by [1m- [0mmatches any character with
	  ASCII value between the pair (inclusive of the pair).
	  If the first character is a [1m! [0mthe sense of the pattern
	  is inverted and it matches any character which is not
	  given.

     [1mQuoting

     [0mThe following characters have a special meaning to the shell
     and cause termination of a word unless quoted.

	  [1m;   &   (   )   |   <   >   newline	space	tab

     [0mA character may be _q_u_o_t_e_d by preceding it with a [1m\ [0mexcept
     that the pair [1m\<newline> [0mis ignored.  No special interpreta-
     tion is made for a quoted character, thus it becomes part of
     the _w_o_r_d which is made up of the adjacent characters.  All
     characters enclosed between a pair of single quote marks
     ([1m''[0m), except a single quote itself, are quoted.  Inside dou-
     ble quotes ([1m""[0m) parameter and command substitution occurs
     and [1m\ [0mmust be used to quote the characters [1m\ " [0mand [1m$ [0mand may
     also be used to quote [1m' [0m(thus [1m\' [0mwill be replaced by [1m'[0m, how-
     ever a [1m' [0mon its own will not be interpreted specially).
     Also the parameter substitution [1m$@ [0mis specially interpreted,
     so that, although [1m"$*" [0mis equivalent to [1m"$1 $2 ..." "$@" [0mis
     equivalent to [1m"$1" "$2" ... .  [0mThus, within double quotes,
     [1m$@ [0mitself is replaced by [1m$1" "$2" ... "$n.

     Prompting

     [0mWhen used interactively, the shell prompts with the value of
     [1mPS1 [0mbefore reading a command.  If at any time a newline is
     typed and further input is needed to complete a command, the
     secondary prompt ([1mPS2[0mis issued.

     [1mInput and Output

     [0mBefore a command is executed its input and output may be
     redirected using a special notation interpreted by the
     shell.  The following may appear anywhere in a _s_i_m_p_l_e _c_o_m_-
     _m_a_n_d or may precede or follow a _c_o_m_m_a_n_d and are not passed
     on to the invoked command.  Substitution and pattern match-
     ing occur before _w_o_r_d or _d_i_g_i_t is used.

     [1m<[0m_w_o_r_d
	  Use file _w_o_r_d as standard input (file descriptor 0).

     [1m>[0m_w_o_r_d
	  Use file _w_o_r_d as standard output (file descriptor 1).
	  If the file does not exist, it is created; otherwise it
	  is truncated to zero length.



Printed 22/5/92     Revision 1.6 of 22/10/90			7






SH(1)		    UNIX Programmer's Manual		    SH(1)



     [1m>>[0m_w_o_r_d
	  Use file _w_o_r_d as standard output.  If the file exists,
	  output is appended (by seeking to the end); otherwise
	  the file is created.

     [1m<<[0m[[1m-[0m]_w_o_r_d
	  The shell input is read up to a line the same as _w_o_r_d,
	  or end of file.  The resulting characters become the
	  standard input.  If any character of _w_o_r_d is quoted, no
	  interpretation is placed upon the characters of the
	  document; otherwise, parameter and command substitution
	  occurs: [1m\newline [0mis removed from the input, and [1m\ [0mmust
	  be used to quote the characters [1m\ $ ' [0mand the first
	  character of _w_o_r_d if it appears as a line of input.  In
	  this last case the [1m\ [0mwill not be removed from the
	  input.

     [1m<&[0m_d_i_g_i_t
	  The standard input is duplicated from file descriptor
	  _d_i_g_i_t; see _d_u_p(2).  Similarly for the standard output
	  using [1m>&[0m_d_i_g_i_t.

     [1m<&-  [0mThe standard input is closed.  Similarly for the stan-
	  dard output using [1m>-[0m.

     If one of the above is preceded by a digit, the file
     descriptor created is that specified by the digit (instead
     of the default 0 or 1).  For example,

	  ... [1m2>&1

     [0mcauses file descriptor 2 to be a duplicate of file descrip-
     tor 1.

     Such redirections are interpreted from left to right, each
     taking effect immediately.  Thus the order of redirections
     is significant if the [1m& [0mnotation is used - the file descrip-
     tor to be duplicated (to the right of the [1m&[0m) must be
     corrected set up before the [1m& [0mredirection.  This behaviour
     can be used to swap file descriptors (using an intermediate
     descriptor) if desired.   Notice that the notation imposes a
     limit ([1m0[0m-[1m9[0m) on the number of file descriptors which can be
     redirected, this is not normally a problem as no standard
     program accesses descriptors beyond [1m2[0m.

     If a command is followed by [1m& [0mthen the default standard
     input for the command is the empty file (/_d_e_v/_n_u_l_l).  Other-
     wise, the environment for the execution of a command con-
     tains the file descriptors of the invoking shell as modified
     by input output specifications.





Printed 22/5/92     Revision 1.6 of 22/10/90			8






SH(1)		    UNIX Programmer's Manual		    SH(1)



     Redirection of output is not allowed in the restricted
     shell.

     [1mEnvironment

     [0mThe environment is a list of name-value pairs that is passed
     to an executed program in the same way as a normal argument
     list; see _e_x_e_c_v_e(2) and _e_n_v_i_r_o_n(7).  The shell interacts
     with the environment in several ways.  On invocation, the
     shell scans the environment and creates a _p_a_r_a_m_e_t_e_r for each
     name found, giving it the corresponding value.  Executed
     commands inherit the same environment.  If the user modifies
     the values of these _p_a_r_a_m_e_t_e_r_s or creates new ones, none of
     these affects the environment unless the [1mexport [0mcommand is
     used to bind the shell's _p_a_r_a_m_e_t_e_r to the environment.  The
     environment seen by any executed command is thus composed of
     any unmodified name-value pairs originally inherited by the
     shell, plus any modifications or additions, all of which
     must be noted in [1mexport [0mcommands.

     The environment for any _s_i_m_p_l_e _c_o_m_m_a_n_d may be augmented by
     prefixing it with one or more assignments to _p_a_r_a_m_e_t_e_r_s.
     Thus these two lines are equivalent

	  TERM=450 cmd args
	  (export TERM; TERM=450; cmd args)

     If the [1m-k [0mflag is set, _a_l_l keyword arguments are placed in
     the environment, even if the occur after the command name.
     In the following the first _e_c_h_o prints "a=b c", the second
     "c":

	  echo a=b c
	  set -k
	  echo a=b c

     [1mSignals
     [0mThe INTERRUPT and QUIT signals for an invoked command are
     ignored if the command is followed by [1m&[0m; otherwise signals
     have the values inherited by the shell from its parent.
     (But see also the [1mtrap [0mcommand below).  Job control signals
     ([1mSIGTSTP[0m, [1mSIGTTIN[0m, and [1mSIGTTOU[0m) retain the handling which
     they have on entry to the shell - they are either ignored if
     the shell executes in an environment without job control
     facilities or the default action (stopping the shell) will
     be in place if process management facilities are available
     (for example from _c_s_h(1)).  The [1mtrap [0mcommand cannot be used
     to intercept these signals.

     Most signals which were not ignored on entry to the shell
     cause the shell to exit if received directly by the shell.
     Some, such as [1mSIGWINCH [0mand [1mSIGCONT [0mare left with their



Printed 22/5/92     Revision 1.6 of 22/10/90			9






SH(1)		    UNIX Programmer's Manual		    SH(1)



     default action - any signal which defaults to being dis-
     carded (see _s_i_g_v_e_c(2)) will retain the default action unless
     trapped using the [1mtrap [0mcommand.  Other signals are trapped
     and either cause control to return to the top (interactive)
     level in the shell (a non-interactive shell will exit) or
     cause the shell to exit.  Normally a signal which
     corresponds to a serious error in a program and would cause
     a core dump to be produced causes the shell to exit, other
     signals just cause return to the top level.

     [1mExecution

     [0mEach time a command is executed the above substitutions are
     carried out.  If the command name matches one of the "[1mSpe-
     cial Commands[0m" below then that command is executed, else if
     the command name matches a function the body of that func-
     tion is executed (and so on, recursively). If neither of
     these cases apply a new process is created and an attempt is
     made to execute the command via an _e_x_e_c_v_e(2).

     The variable [1mPATH [0mdefines the search path for the directory
     containing the command.  Each alternative directory name is
     separated by a colon ([1m:[0m).	The default path is [1m:/usr/bin
     [0malthough this is almost invariably set by the process which
     executed the shell.  If the command name contains a /, the
     search path is not used; although the restricted shell will
     not execute the command in this case.  Otherwise, each
     directory in the path is searched for an executable file.
     If the file has execute permission but is not an _a._o_u_t(5)
     file, it is assumed to be a file containing shell commands.
     A subshell (i.e., a separate process) is spawned to read it.
     A parenthesized command is also executed in a subshell.

     To speed up command location the place where each executed
     command is located is remembered by the shell.  If the path
     to the command is relative to the current directory this
     information will be discarded when the current directory
     changes (using [1mcd[0m).  Otherwise the information is discarded
     when the [1mPATH [0mvariable is changed or when explicitly
     requested using [1mhash -r[0m. This means that, if a new command
     is added to a directory on the shell [1mPATH [0mahead of the loca-
     tion of an old command of the same name the new command will
     not be noticed by the shell until it resets its command
     location information.

     [1mSpecial Commands

     [0mThe following commands are executed in the shell process
     however normal command line processing occurs, including
     input and output redirection (although this is not port-
     able).




Printed 22/5/92     Revision 1.6 of 22/10/90		       10






SH(1)		    UNIX Programmer's Manual		    SH(1)



     [1m:	  [0mNo effect; the command does nothing.	The exit status
	  is 0.
     [1m. [0m_f_i_l_e
	  Read and execute commands from _f_i_l_e and return.  The
	  search path [1m$PATH [0mis used to find the directory con-
	  taining _f_i_l_e.
     [1mbreak [0m[_n]
	  Exit from the enclosing [1mfor [0mor [1mwhile [0mloop, if any.  If
	  _n is specified, break _n levels.
     [1mcontinue [0m[_n]
	  Resume the next iteration of the enclosing [1mfor [0mor [1mwhile
	  [0mloop.  If _n is specified, resume at the _n-th enclosing
	  loop.
     [1mcd [0m[_a_r_g]
	  Change the current directory to _a_r_g.	The shell vari-
	  able [1mHOME [0mdefines the default _a_r_g.  The variable [1mCDPATH
	  [0mdefines a search path for the directory _a_r_g.	It con-
	  sists of a colon ([1m:[0m) separated list of directories each
	  of which is searched, in turn, for _a_r_g.  The default
	  [1mCDPATH [0mis the an empty string, which effectively means
	  the current directory.
     [1mecho [0m[_a_r_g ...]
	  The arguments are echoed to standard output.	The com-
	  mand behaves as _e_c_h_o(1v) unless the [1m-b [0mflag is in
	  effect, in which case it behaves as _e_c_h_o(1)).  The pri-
	  mary difference is in the interpretation of [1m\ [0mescape
	  sequences (only done if [1m-b [0mis not in effect) and the
	  recognition of a leading [1m-n [0margument - which only
	  occurs if [1m-b [0mis in effect in the shell.
     [1meval [0m[_a_r_g ...]
	  The arguments are read as input to the shell and the
	  resulting command(s) executed.
     [1mexec [0m[_a_r_g ...]
	  The command specified by the arguments is executed in
	  place of this shell without creating a new process.
	  Input output arguments may appear and, if no other
	  arguments are given, cause the shell input output to be
	  modified without executing a new process.
     [1mexit [0m[_n]
	  Causes a shell to exit with the exit status specified
	  by _n.  If _n is omitted, the exit status is that of the
	  last command executed.  (An end of file will also exit
	  from the shell.)
     [1mexport [0m[_n_a_m_e ...]
	  The given names are marked for automatic export to the
	  _e_n_v_i_r_o_n_m_e_n_t of subsequently-executed commands.  If no
	  arguments are given, a list of exportable names is
	  printed.  Functions cannot be exported, defining a
	  function with the same name as an exported variable
	  will cancel the export of the variable as well as des-
	  troying the variable.
     [1mhash [0m[[1m-r[0m] [_n_a_m_e]



Printed 22/5/92     Revision 1.6 of 22/10/90		       11






SH(1)		    UNIX Programmer's Manual		    SH(1)



	  If [1m-r [0mis given the information about command location
	  is discarded.  If no arguments are given information
	  about all currently remembered commands is printed,
	  else for each _n_a_m_e the shell determines and stores the
	  location of the command of that name.
     [1mlogin [0m[_a_r_g ...]
	  Equivalent to 'exec login arg ...'.
     [1mpwd  [0mPrints the current directory on the standard output.
	  See the manual page _p_w_d(1) for more information.
     [1mread [0m_n_a_m_e ...
	  One line is read from the standard input; successive
	  words of the input are assigned to the variables _n_a_m_e
	  in order, with leftover words to the last variable.
	  The return code is 0 unless the end-of-file is encoun-
	  tered.
     [1mreadonly [0m[_n_a_m_e ...]
	  The given names are marked readonly, the values of the
	  these names may not be changed by subsequent assign-
	  ment.  If no arguments are given, a list of all
	  readonly names is printed.
     [1mreturn [0m[_n]
	  Terminates the current function causing the exit status
	  to be _n.  This command is illegal outside a function
	  definition.  If _n is not given the exit status will be
	  that of the last command executed (normally the previ-
	  ous command).
     [1mset [0m[[1m-abefhkntuvx [0m[_a_r_g ...]]
	  The [1mset [0mcommand allows various aspects of the behaviour
	  of the shell to be controlled.
	  [1m-a [0mAutomatically export any variable which is created
	     or modified.
	  [1m-b [0mTurn on BSD compatibility for the [1mecho [0mcommand.  See
	     the description of [1mecho [0mabove.
	  [1m-e [0mIf non interactive, exit immediately if a command
	     fails.  This option does not cause the shell to exit
	     if the test in an [1mif [0mor [1mwhile [0mcommand fails,
	     although this may happen in other implementations of
	     the shell.
	  [1m-f [0mPrevent pattern matching within words.  The process-
	     ing detailed in the "[1mFilename Generation[0m" subsection
	     is not done.
	  [1m-h [0mLocate commands within function definitions when the
	     function is defined.  This does not mean that a sub-
	     sequent change to the shell [1mPATH [0mvariable will not
	     change which commands are executed when a previously
	     defined function is executed.  All the [1m-h [0mflag does
	     is to cause commands in a function definition to be
	     looked up when the function is defined and hence
	     remembered in the command location table (see the
	     [1mhash [0mcommand above).  When the function is executed
	     the commands will be checked against the location
	     table again and the current location will be used.



Printed 22/5/92     Revision 1.6 of 22/10/90		       12






SH(1)		    UNIX Programmer's Manual		    SH(1)



	  [1m-k [0mAll (apparent) shell variable arguments are placed
	     in the environment for a command, not just those
	     that precede the command name.  As a consequence any
	     command argument resembling a shell variable assign-
	     ment must be quoted.
	  [1m-n [0mRead commands but do not execute them.  Notice that
	     this cannot be undone by the "[1mset +n[0m" command as it
	     will not be executed.
	  [1m-t [0mExit after reading and executing one command.
	  [1m-u [0mTreat unset variables as an error when substituting.
	  [1m-v [0mPrint shell input lines as they are read, the output
	     is printed on the error stream.
	  [1m-x [0mPrint commands and their arguments as they are exe-
	     cuted.  The command will be preceded by a "[1m+[0m".  The
	     command is printed on the error stream.

	  If "[1m+[0m" is used in place of "[1m-[0m" the corresponding
	  options are switched off.  If the first argument to [1mset
	  is a single - [0mthe [1mx [0mand [1mv [0moptions are switched off
	  (this is for backwards compatibility with previous ver-
	  sions of the shell which did not recognise the "[1m+[0m" form
	  of the [1mset [0mcommand).	If the first argument is [1m-- [0mno
	  flag settings are changed.

	  These flags can also be used upon invocation of the
	  shell, in either or both the "[1m-[0m" or "[1m+[0m" form.  The
	  current set of flags may be found in [1m$-[0m.

	  Remaining arguments are positional parameters and are
	  assigned, in order, to [1m$1[0m, [1m$2[0m, etc.  If the first argu-
	  ment begins with "[1m-[0m" or "[1m+[0m" and no flags are turned on
	  or off the [1m-- [0margument should be used.  If no arguments
	  are given, the values of all names are printed.

     [1mshift [0m[_n]
	  The positional parameters from [1m$[0m_n+1...  are renamed
	  [1m$1[0m...  _n defaults to 1 (renaming [1m$2 [0mto [1m$1 [0mand so on).

     [1msuspend
	  [0mThis command stops the execution of the shell in an
	  environment in which there are job control facilities
	  and is ignored otherwise.  The command is equivalent to
	  "[1mkill -TSTP $$[0m".  If the [1mSIGTSTP [0msignal is ignored by
	  the shell this has no effect, if it is set to the
	  default action (which should only arise if the process
	  which invoked the shell was executing in an environment
	  which supports job control) the shell will stop and
	  control will return to the job control process.

     [1mtest [0mThe arguments specify various conditions to check.  The
	  exit status of the command is controlled by the result
	  of the tests.  See the manual entry _t_e_s_t(1v) for a



Printed 22/5/92     Revision 1.6 of 22/10/90		       13






SH(1)		    UNIX Programmer's Manual		    SH(1)



	  complete description of the arguments.  Notice that the
	  command syntax is an extension of that supplied by the
	  _t_e_s_t command /_u_s_r/_b_i_n/_t_e_s_t described in _t_e_s_t(1).

     [1mtimes
	  [0mPrint the accumulated user and system times for
	  processes run from the shell.

     [1mtrap [0m[_a_r_g] [_n] ...
	  _A_r_g is a command to be read and executed when the shell
	  receives signal(s) _n.  (Note that _a_r_g is scanned once
	  when the trap is set and once when the trap is taken.)
	  Trap commands are executed in order of signal number.
	  Signals ignored when the shell is started remain
	  ignored - [1mtrap [0mcommands for these signals will there-
	  fore be silently ignored.  The [1mSIGSEGV [0msignal and job
	  control signals which default to stopping a process
	  (see _s_i_g_v_e_c(2)) cannot be trapped - these signals are
	  [1mSIGTSTP SIGTTIN [0mand [1mSIGTTOU[0m.	If _a_r_g is absent but sig-
	  nals are given, all the trap(s) _n are reset to their
	  original values.  If _a_r_g is the null string, this sig-
	  nal will be ignored by the shell and by invoked com-
	  mands.  If _n is 0, the command _a_r_g is executed on exit
	  from the shell, otherwise upon receipt of signal _n as
	  numbered in _s_i_g_v_e_c(2).  _T_r_a_p with no arguments prints a
	  list of commands associated with each signal number.
	  If a single argument is given and it is [1m-f [0ma list of
	  all traps is given together with the signal name will
	  the initial [1mSIG [0mremoved.  If the single argument is [1m-l
	  [0ma list of all allowed signal arguments is given
	  together with their signal name with the initial [1mSIG
	  [0mremoved and a short explanation of the signal.  Notice
	  that, although [1mSIGKILL [0mand [1mSIGSTOP [0mare valid for the
	  trap command the kernel will silently ignore requests
	  to trap them.  As an extension to the normal syntax a
	  trap number may be replaced by the signal name with the
	  initial [1mSIG [0mremoved - notice that this is not portable.

     [1mtype [0m[_n_a_m_e ...]
	  For each command _n_a_m_e the shell prints a line indicat-
	  ing where the command is located (including whether it
	  is a shell built-in or a function).

     [1mulimit [0m[[1m-f[0m] [_n]
	  The [1m-f [0moption is the default and has no effect on the
	  command.  The command limits the size of files created
	  by the shell to _n*512 bytes.	The limit affects the
	  shell and all processes started from it.  Only the
	  super-user can increase the limit.  Without an argument
	  [1mulimit [0mprints the current size limit.

     [1mumask [0m[_n_n_n]



Printed 22/5/92     Revision 1.6 of 22/10/90		       14






SH(1)		    UNIX Programmer's Manual		    SH(1)



	  The user file creation mask is set to the octal value
	  _n_n_n (see _u_m_a_s_k(2)).  If _n_n_n is omitted, the current
	  value of the mask is printed.

     [1munset [0m[_n_a_m_e ...]
	  Each variable or function named by _n_a_m_e is deleted.  If
	  the variable is exported to the environment it will
	  also be removed from the environment of the shell and
	  all processes started from it.  The variables [1mPATH[0m,
	  [1mPS1[0m, [1mPS2[0m, [1mMAILCHECK [0mand [1mIFS [0mcannot be deleted.

     [1mwait [0m[_n]
	  Wait for the specified process and report its termina-
	  tion status.	If _n is not given, all currently active
	  child processes are waited for.  The return code from
	  this command is that of the process waited for.

     [1mInvocation

     [0mIf the first character of argument zero is [1m-[0m, commands are
     read from /_e_t_c/_p_r_o_f_i_l_e then from [1m$HOME/[0m._p_r_o_f_i_l_e[1m, [0mif such
     files exist.  Commands are then read as described below.
     The shell can be given option arguments starting with "[1m-[0m" or
     "[1m+[0m" with the same interpretation as the arguments to the [1mset
     [0mcommand above.  In addition four extra option letters are
     recognised.  Notice that the arguments after the option
     letters are interpreted as the name of a file containing
     shell commands followed by values for the positional vari-
     ables (see "[1mParameter Substitution[0m" above), unless the [1m-c [0mor
     [1m-s [0moption is given.
     [1m-c [0m_s_t_r_i_n_g	If the [1m-c [0mflag is present, _s_t_r_i_n_g is interpreted
		as a sequence of commands to execute.  The
		remaining arguments are assigned to the posi-
		tional variables in turn.
     [1m-s         [0mIf the [1m-s [0mflag is present or if no arguments
		remain then commands are read from the standard
		input.	The arguments after the option arguments
		are assigned in turn to the positional variables.
		Output produced by the shell (except for non-
		error output from positional commands) is written
		to file descriptor 2.
     [1m-i         [0mIf the [1m-i [0mflag is present or if the shell input
		and output are attached to a terminal (as told by
		_i_s_a_t_t_y(3)) then this shell is _i_n_t_e_r_a_c_t_i_v_e. In
		this case the terminate signal [1mSIGTERM [0m(see
		_s_i_g_v_e_c(2)) is ignored (so that "[1mkill 0[0m" does not
		kill an interactive shell) and the interrupt sig-
		nal [1mSIGINT [0mis caught and ignored (so that [1mwait [0mis
		interruptible).  In all cases [1mSIGQUIT [0mis ignored
		by the shell.
     [1m-r         [0mIf the [1m-r [0mflag is present, or the name of the
		shell is _r_s_h (as found from argument 0) or the



Printed 22/5/92     Revision 1.6 of 22/10/90		       15






SH(1)		    UNIX Programmer's Manual		    SH(1)



		[1mSHELL [0menvironment variable contains a letter "r"
		the shell behaves as a restricted shell (see the
		next subsection).

     The remaining flags and arguments are described under the
     [1mset [0mcommand.

     [1mThe Restricted Shell

     [0mThe shell becomes a restricted shell if invoked with the [1m-r
     [0mflag or if its name is _r_s_h or the file name in the [1mSHELL
     [0menvironment variable contains an "r" character (as described
     above).

     The restricted shell provides a controlled environment for
     untrusted users or processes.  Certain built-in commands
     cannot be executed and external commands must not be speci-
     fied using absolute path names:

     [1mcd       [0mThis command cannot be executed.	The _r_s_h user is
	      thus forced to remain in their initial directory.

     _c_o_m_m_a_n_d_s The names of commands to be executed must not con-
	      tain the "[1m/[0m" character; thus all commands must be
	      in the [1mPATH [0mor in the current directory.

     [1mPATH     [0mThis shell variable cannot be changed - thus the
	      range of commands available to the _r_s_h user is
	      known.

     _I_O       Input and output redirection is forbidden; thus the
	      user can only write to or create new files using
	      the supplied commands.

     These restrictions come into effect after the system and
     user ._p_r_o_f_i_l_e files have been executed, thus these can be
     used to provide appropriate facilities to the user.

[1mEXIT STATUS
     [0mThe exit status of the shell is the exit status of the last
     command executed (ie the status in [1m$?[0m) unless the [1mexit [0mcom-
     mand is used to terminate the shell.  Errors within the
     input to the shell (for example bad syntax or non-existent
     commands) cause a failure status to be set:

     [1m1	  [0mNon-existent command or a similar recoverable error,
	  including errors in built-in commands.

     [1m2	  [0mSyntax error (for example a badly formed [1mif [0mcommand).

     Unless the [1m-e [0mflag is in effect a failure code of "[1m1[0m" causes
     the shell to output an error message and continue, whereas a



Printed 22/5/92     Revision 1.6 of 22/10/90		       16






SH(1)		    UNIX Programmer's Manual		    SH(1)



     failure code of "[1m2[0m" causes the shell to terminate the opera-
     tion.  If the shell is interactive control will be returned
     to the user, if it is not interactive the shell will exit
     with the relevant status code.  The shell will exit on any
     failure if the [1m-e [0mflag is in effect (an interactive shell
     will also exit).

[1mNOTES
     [0mThe facilities for operation within an environment which
     supports job control are extremely limited.  Even without
     job control _s_h could handle the job control signals, however
     it is normally the case that these will only arise if the
     shell is running under the control of another (job control)
     process, such as _c_s_h(1).

[1mFILES
     [0m/etc/profile
     $HOME/[1m.[0mprofile
     /tmp/sh*
     /dev/null

[1mSEE ALSO
     [0mcd (1), csh(1), echo (1v), echo (1), pwd (1), test(1), umask
     (1), execve(2), environ(7)































Printed 22/5/92     Revision 1.6 of 22/10/90		       17



[0m