Bourne | Ash |  #!  | find | ARG_MAX | Shells | portability | permissions | UUOC | - | ../Various | HOME
"$@" | echo/printf | set -e | test | tty defs | tty chars | $() vs ) | IFS | using siginfo | nanosleep | line charset | locale


Manual of the PWB (aka Mashey) Shell

released under the license of Caldera

original sh.1 (and all referenced pages) massaged, nroffed and htmlized.

sh(1) doesn't contain a reference to the echo command, here it is: echo(I).


SH (I)                       5/31/77                       SH (I)


NAME
     sh	 -  shell (command interpreter)

SYNOPSIS
     sh	[ -v ] [ - ] [ -ct ] [ name [ arg1 ... ] ]

DESCRIPTION
     Sh	is the standard	command	interpreter.  It is  the  program
     which  reads and arranges the execution of	the command lines
     typed by most users.  It may itself be called as  a  command
     to	interpret files	of commands.  Before discussing	the argu-
     ments to the Shell	when it	is used	as a command, the  struc-
     ture of command lines themselves will be given.

     Commands. Each command is a sequence  of  non-blank  command
     arguments separated by blanks.  The first argument	specifies
     the name of a command to be executed.   Except  for  certain
     types  of	special	 arguments discussed below, the	arguments
     other than	the command name are passed  without  interpreta-
     tion to the invoked command.

     By	default, if the	first argument is the name of an  execut-
     able  file, it is invoked;	otherwise the string ``/bin/'' is
     prepended to the argument.	 (In this way most standard  com-
     mands,  which  reside  in	``/bin'', are found.)  If no such
     command is	found, the string ``/usr'' is  further	prepended
     (to  give	``/usr/bin/command'') and another attempt is made
     to	execute	the resulting file.   (Certain	lesser-used  com-
     mands  live  in ``/usr/bin''.)  If	a command name contains	a
     ``/'', it is invoked as is, and no	prepending  ever  occurs.
     This  standard command search sequence may	be changed by the
     user.  See	the description	 of  the  Shell	 variable  ``$p''
     below.

     If	a non-directory	file exists that matches the command name
     and  has  executable mode,	but not	the form of an executable
     program (does not begin with the proper magic  number)  then
     it	 is  assumed  to  be  an ASCII file of commands	and a new
     Shell is created to execute it.   See  ``Argument	passing''
     below.

     If	the file cannot	be found, a diagnostic is printed.

     Command lines. One	or more	commands separated  by  ``|''  or
     ``^''  constitute	a  chain  of  filters, or a pipeline. The
     standard output of	each command but the last is taken as the
     standard  input of	the next command.  Each	command	is run as
     a separate	process, connected by pipes (see pipe(II)) to its
     neighbors.	  A command line contained in parentheses ``( )''
     may appear	in place of a simple command as	a filter.

     A command line consists of	one or more pipelines  separated,
     and  perhaps  terminated  by ``;''	or ``&'', or separated by
     ``||'' or ``&&''.  The semicolon designates sequential  exe-
     cution.   The  ampersand causes the following pipeline to be
     executed without waiting for the preceding	pipeline to  fin-
     ish.   The	process	id of the preceding pipeline is	reported,
     so	that it	may be used if necessary for a subsequent wait or
     kill.  A  pipeline	 following ``&&'' is executed only if the
     preceding pipeline	completed successfully (exit code  zero),
     while  that following ``||'' is executed only if the preced-
     ing one did not execute successfully (exit  code  non-zero).
     The  exit  code  tested  is  that of the last command in the
     pipeline.  The ``&&'' operator has higher precedence.

     Termination Reporting. If a command (not followed by  ``&'')
     terminates	 abnormally, a message is printed.  (All termina-
     tions other than exit and interrupt  are  considered  abnor-
     mal).   Termination  reports  for commands	followed by ``&''
     are given upon receipt of the first  command  subsequent  to
     the  termination of the command, or when a	wait is	executed.
     The following is a	list of	 the  abnormal	termination  mes-
     sages:

	  Bus error
	  Trace/BPT trap
	  Illegal instruction
	  IOT trap
	  EMT trap
	  Bad system call
	  Quit
	  Floating exception
	  Memory violation
	  Killed
	  Broken Pipe
	  Alarm	clock
	  Terminated

     If	a core image is	produced, ``- Core dumped''  is	 appended
     to	the appropriate	message.

     Redirection of I/O. There are three character sequences that
     cause  the	immediately following string to	be interpreted as
     a special argument	to the Shell itself.   Such  an	 argument
     may appear	anywhere among the arguments of	a simple command,
     or	before or after	a  parenthesized  command  list,  and  is
     associated	with that command or command list.

     An	argument of the	form ``<arg'' causes the file ``arg''  to
     be	 used  as  the	standard input (file descriptor	0) of the
     associated	command.

     An	argument of the	form ``>arg'' causes file ``arg''  to  be
     used  as  the  standard  output  (file descriptor 1) for the
     associated	command.  ``Arg'' is created if	it did not exist,
     and in any	case is	truncated at the outset.

     An	argument of the	form ``>>arg'' causes file ``arg'' to  be
     used  as the standard output for the associated command.  If
     ``arg'' did not exist, it is created; if it did  exist,  the
     command output is appended	to the file.

     For example, either of the	command	lines

	  ls >junk; cat	tail >>junk
	  ( ls;	cat tail ) >junk

     creates, on file ``junk'',	a listing of the  working  direc-
     tory, followed immediately	by the contents	of file	``tail''.

     Either of the constructs ``>arg''	or  ``>>arg''  associated
     with  any but the last command of a pipeline is ineffectual,
     as	is ``<arg'' in any but the first.

     In	commands called	by the Shell, file descriptor 2	refers to
     the  standard output of the Shell regardless of any redirec-
     tion of standard output.  Thus filters may	write diagnostics
     to	a location where they have a chance to be seen.

     A redirection of the form ``<-''  requests	 input	from  the
     standard  input  that existed when	the instance of	the Shell
     was created.  This	permits	a command file to be treated as	a
     filter.  The procedure ``lower'' could be used in a pipeline
     to	convert	characters to lower case:

	  tr "[A-Z]" "[az]" <--

     A typical invocation might	be:

	  reform -8 -c <prnt0 | lower >prnt0a

     Generation	of argument lists. If any argument  contains  any
     of	 the characters	``?'', ``*'' or	``['', it is treated spe-
     cially as follows.	 The current directory	is  searched  for
     files which match the given argument.

     The character ``*'' in an argument	 matches  any  string  of
     characters	in a file name (including the null string).

     The character ``?'' matches any single non-null character in
     a file name.

     Square brackets ``[...]''	specify	 a  class  of  characters
     which  matches  any single	file name character in the class.
     Within the	brackets, each ordinary	character is taken to  be
     a	member	of  the	class.	A pair of characters separated by
     ``-'' places in the class each character  lexically  greater
     than  or  equal  to  the first and	less than or equal to the
     second member of the pair.

     Other characters match only the same character in	the  file
     name.

     If	an argument starts with	 ``*'',	 ``?'',	 or  ``['',  that
     argument  will  not  match	 any  file  name that starts with
     ``.''.

     For example, ``*''	matches	all file names;	``?'' matches all
     one-character file	names; ``[ab]*.s'' matches all file names
     beginning with  ``a''  or	``b''  and  ending  with  ``.s'';
     ``?[zi-m]'' matches all two-character file	names ending with
     ``z'' or the letters ``i''	through	 ``m''.	  None	of  these
     examples match names that start with ``.''.

     If	the argument with ``*''	or ``?'' also contains a ``/'',	a
     slightly  different  procedure  is	 used:	 instead  of  the
     current directory,	the directory used is the one obtained by
     taking  the  unmodified  argument to the ``/'' preceding the
     first ``*?[''.  The matching process matches  the	remainder
     of	 the  argument	after this ``/'' against the files in the
     derived directory.	 For example:  ``/usr/dmr/a*.s''  matches
     all  files	 in directory ``/usr/dmr'' which begin with ``a''
     and end with ``.s''.

     In	any event, a list of names is obtained	which  match  the
     argument.	 This list is sorted into alphabetical order, and
     the resulting sequence  of	 arguments  replaces  the  single
     argument  containing  the	``*'', ``['', or ``?''.	 The same
     process is	carried	out  for  each	argument  (the	resulting
     lists are not merged) and finally the command is called with
     the resulting list	of arguments.

     If	a command has one argument with	``*'', ``?'', or ``['',	a
     diagnostic	 is printed if no file names match that	argument.
     If	a command has several such  arguments,	a  diagnostic  is
     only printed if they all fail to match any	files.

     Quoting. The character ``\'' causes the immediately  follow-
     ing character to lose any special meaning it may have to the
     Shell;  in	this way ``<'', ``>'', and other characters mean-
     ingful  to	 the Shell may be passed as part of arguments.	A
     special case of this feature allows the continuation of com-
     mands onto	more than one line:  a new-line	preceded by ``\''
     is	translated into	a blank.

     A sequence	of characters enclosed in single  quotes  (')  is
     taken  literally, with no substitution or special processing
     whatsoever.

     Sequences of characters enclosed in double	 quotes	 (")  are
     also  taken  literally,  except that ``\'', ``"'',	and ``$''
     are handled specially.   The  sequences  ``\"''  and  ``\$''
     yield  ``"''  and ``$'', respectively.  The sequence ``\x'',
     where ``x'' is any	character except ``"'' or  ``$'',  yields
     ``\x''.   A ``$'' within a	quoted string is processed in the
     same manner as a ``$'' that is not	in a quoted  string  (see
     below), unless it is preceded by a	``\''.	For example:

	  ls | pr -h "\\"My directory\"\$"

     causes a directory	listing	to be produced by ls, and  passed
     on	 to  pr	 to  be	 printed  with	the heading ``\"My direc-
     tory"$''.	Quotes permit the  inclusion  of  blanks  in  the
     heading,  which  is a single argument to pr. Note that ``\''
     inside quotes disappears only when	preceding ``$''	or ``"''.

     Argument passing. When the	Shell is invoked as a command, it
     has  additional string processing capabilities.  Recall that
     the form in which the Shell is invoked is

	  sh [ -v ] [ name [ arg1 ... ]	]

     The name is the name of a file  which  is	read  and  inter-
     preted.  If not given, this subinstance of	the Shell contin-
     ues to read the standard input file.

     In	command	lines in the file (and also  in	 command  input),
     character	sequences of the form ``$N'', where N is a digit,
     are replaced by the nth argument to the  invocation  of  the
     Shell  (argn).   ``$0'' is	replaced by name. Shell	variables
     (``$a'' - ``$z''),	described below, are replaced in the same
     way.

     The special argument  ``$*''  is  a  name	for  the  current
     sequence of all arguments from ``$1'' through the last argu-
     ment, each	argument separated from	the previous by	a  single
     blank.

     The special argument ``$$'' is the	ASCII  representation  of
     the unique	process	number of the current Shell.  This string
     is	useful for creating temporary file names  within  command
     files.

     The sequence ``$x'', where	``x'' is any character except one
     of	the 38 characters mentioned above, is taken to refer to	a
     variable ``x'' whose value	is the null string.  All  substi-
     tution  on	 a  command line occurs	before the line	is inter-
     preted:  no action	that alters the	value of any variable can
     have  any effect on a reference to	that variable that occurs
     on	the same line.

     The argument -t, used alone, causes sh to read the	 standard
     input  for	 a single line,	execute	it as a	command, and then
     exit.  It is useful for  interactive  programs  which  allow
     users to execute system commands.

     The argument -c (used with	one  following	argument)  causes
     the  next	argument  to  be taken as a command line and exe-
     cuted.  No	new-line need be present, but new-line characters
     are  treated  appropriately.   This facility is useful as an
     alternative to -t where the caller	has already read some  of
     the characters of the command to be executed.

     The argument -v (``verbose'') causes every	command	 line  to
     be	 printed after all substitution	occurs,	but before execu-
     tion.  Each argument is preceded by a  single  blank.   When
     given, the	-v must	be the first argument.

     Used alone, the argument ``-'' suppresses prompting, and  is
     commonly used when	piping commands	into the Shell:

	  ls | sed "s/.*/echo &:;cat &/"  |  sh -

     prints all	files in a directory, each prefaced by its name.

     Initialization. When the Shell is	invoked	 under	the  name
     ``-''  (as	 it  is	 when you login), it attempts to read the
     file ``.profile'' in the current directory	and  execute  the
     commands  found  there.  When it finishes with ``.profile'',
     the Shell prompts the user	 for  input  as	 usual.	  Typical
     files  contain commands to	set terminal tabs and modes, ini-
     tialize values of Shell variables,	look at	mail, etc.

     End of file. An end-of-file in the	Shell's	input  causes  it
     to	 exit.	 A side	effect of this fact means that the way to
     log out from UNIX is to type an EOT.

     Command file errors; interrupts. Any  Shell-detected  error,
     or	 an  interrupt	signal,	during the execution of	a command
     file causes the Shell  to	cease  execution  of  that  file.
     (Except after onintr; see below.)

     Processes that are	created	 with  ``&''  ignore  interrupts.
     Also  if  such a process has not redirected its input with	a
     ``<'', its	input is automatically redirected  to  come  from
     the zero length file ``/dev/null''.

     Special commands. The following commands  are  treated  spe-
     cially  by	 the Shell.  These commands generally do not work
     when named	as arguments to	programs like time, if,	or  nohup
     because  in these cases they are not invoked directly by the
     Shell.

     chdir and cd are done without spawning a new process by exe-
     cuting chdir(II).

     login is done by executing	``/bin/login'' without creating	a
     new process.

     wait is done without spawning a  new  process  by	executing
     wait(II).

     shift [ integer ] is done by manipulating the  arguments  to
     the  Shell.   In  the  normal  case, shift	has the	effect of
     decrementing the Shell argument names by one (``$1''  disap-
     pears,  ``$2''  becomes  ``$1'',  etc.).	When the optional
     integer is	given, only arguments equal to	or  greater  than
     that number are shifted.

     ``:'' is simply ignored.

     ``='' name	[ arg1 [ arg2 ]	]
     The single	character Shell	variable  (name)  is  assigned	a
     value,  either  from the optional argument(s), or from stan-
     dard input.  If a single argument is  given,  its	value  is
     used.   If	 a second argument is included,	its value is used
     only if the first argument	has a null value.  This	permits	a
     simple way	of setting up default values for arguments:

	  = a "$1" default

     causing default to	be used	if  ``$1''  is	null  or  omitted
     entirely.

     Such variables are	referred to later with	a  ``$''  prefix.
     The  variables  ``$a''  through  ``$m'' are guaranteed to be
     initialized to null, and will never have  special	meanings.
     The variables ``$n'' through ``$z'' are not guaranteed to be
     initialized to null, and may, at some time	 in  the  future,
     acquire  special  meanings.  Currently, these variables have
     predefined	meanings:

     $n	  is the argument count	to the Shell command.

     $p	  contains the Shell directory search sequence	for  com-
     mand  execution.	Alternatives are separated by ``:''.  The
     default initial value is:
	       = p ":/bin:/usr/bin"
     which executes from the current directory	(the  null  path-
     name),  then  from	 ``/bin'',  then  from	``/usr/bin'',  as
     described above.  For the super-user, the value is:
	       = p "/bin:/etc:/"
     Using the same syntax, users may choose their  own	 sequence
     by	 storing  it  in  a  file  named ``.path'' in their login
     directory.	 The ``.path'' information is available	 to  suc-
     cessive  Shells;  the ``$p'' value	is not.	 If the	``.path''
     file contains a second line, it is	interpreted as	the  name
     of	 the  Shell  to	be invoked to interpret	Shell procedures.
     (See ``$z'' below).

     $r	  is the exit  status  code  of	 the  preceding	 command.
     ``0'' is the normal return	from most commands.

     $s	  is your login	directory.

     $t	  is your login	tty letter.

     $w	  is your file system name (first component of ``$s'').

     $z	  is the name of the program to	be invoked when	 a  Shell
     procedure	 is   to  be  executed.	  Its  default	value  is
     ``/bin/sh'', but it can be	overridden by supplying	a  second
     line  in the ``.path'' file.  It can be used to achieve con-
     sistent use of a specific Shell during periods when  several
     distinct  Shells  are  present in the system.  For	safety in
     the presence of change, use ``$z''	as a command rather  than
     ``sh''.

     No	substitution of	variables (or  arguments)  occurs  within
     single  quotes  (').   Within  double quotes ("), a variable
     string is substituted unchanged, even if it contains charac-
     ters  (``"'',  ``\'',  or	``$'')	that  might  otherwise be
     treated specially.	 In particular,	the argument  ``$1''  can
     be	 passed	 unchanged  to another command by using	``"$1"''.
     Outside quotes, substituted characters possess the	same spe-
     cial meanings they	have as	if typed directly.

     To	illustrate, suppose that the shell procedure ``mine''  is
     called with two arguments:

	  sh  mine  'a; echo "$2"'  '"'

     Then sample commands in ``mine'' and  their  output  are  as
     follows:

	  echo '$1'	      $1
	  echo "$1"	      a; echo "$2"
	  echo $1	      a
			      $2
	  echo $2a"	      a
	  echo "$2a"	      "a
	  echo $2	      syntax error

     The appearance of the  string  ``$2''  (rather  than  ``"'')
     occurs  because the Shell performs	only one level of substi-
     tution, i.e., no rescanning is done.

     onintr [ label ]
     Causes control to pass to the label named (using a	goto com-
     mand)  if the Shell command file is interrupted.  After such
     a transfer, interrupts are	re-enabled.   Onintr  without  an
     argument  also  enables interrupts.  The special label ``-''
     will cause	any number of interrupts to be ignored.

     next [ name ]
     This command causes  name	to  become  the	 standard  input.
     Current input is never effectively	resumed.  If the argument
     is	omitted, your terminal keyboard	is assumed.

     pump [ -[subchar] ] [ + ] [ eofstr	]
     This command reads	its standard input until it finds  eofstr
     (defaults	to  ``!''  if not specified) alone on a	line.  It
     normally substitutes the values of	arguments  and	variables
     (marked with ``$''	as usual).  If ``-'' is	given alone, sub-
     stitution is suppressed, and ``-subchar'' causes subchar  to
     be	 used  in  place  of ``$'' as the indicator character for
     substitution.  Escaping is	handled	 as  in	 quoted	 strings:
     the  indicator  character	may be escaped by preceding it by
     ``\''.  Otherwise,	``\'' and other	characters are	transmit-
     ted  unchanged.  If ``+'' is used,	leading	tabs in	the input
     are thrown	away, allowing indentation.  This command may  be
     used interactively	and in pipelines.

     opt [ -v ]	[ +v ] [ -p prompt-str ]
     The argument -v turns on tracing, in the same style as a  -v
     argument  for the Shell.  The argument +v turns it	off.  The
     argument -p causes	the next argument string to  be	 used  as
     the prompt	string for an interactive shell.

     Commands implementing control structure.  Control	structure
     is	provided by a set of commands that happen currently to be
     built into	the Shell, although no guarantee  is  given  that
     this will remain so.  They	are documented separately as fol-
     lows:

	  if(I)	- if, else, endif, and test.
	  switch(I) - switch, breaksw, endsw.
	  while(I) - while, end, break,	continue.
	  goto(I) - goto.
	  exit(I) - exit.

FILES
     /etc/sha, for shell accounting.
     /dev/null as a source of end-of-file.
     .path in login directory to initialize $p and name	of Shell.
     .profile in login directory for general initialization.

SEE ALSO
     The UNIX Time-Sharing System by D.	M. Ritchie and K.  Thomp-
     son,  CACM,  July,	1974, which gives the theory of	operation
     of	the Shell.
     PWB/UNIX Shell Tutorial by	J. R. Mashey.
     chdir(I),	equals(I),  exit(I),  expr(I),  fd2(I),
     login(I),	  loginfo(I),	onintr(I),   pump(I),	shift(I),
     switch(I),	wait(I), while(I), pexec(III), sha(V), glob(VIII)

EXIT CODE
     If	an error occurs	in a command file, the Shell returns  the
     exit  value  ``1''	 to  the  parent process.  Otherwise, the
     current value of the Shell	variable $r is returned.   Execu-
     tion of a command file is terminated by an	error.

BUGS
     There is no built-in way to redirect the diagnostic  output;
     fd2(I) must be used.
     A single command line is limited to 1000  total  characters,
     50	arguments, and approximately 20	operators.