From sources-request@genrad.UUCP Mon Jun 10 07:13:31 1985
Relay-Version: version B 2.10.3 4.3bsd-beta 6/6/85; site seismo.UUCP
Posting-Version: version B 2.10.2 9/3/84; site genrad.UUCP
Path: seismo!cbosgd!ulysses!allegra!mit-eddie!genrad!sources-request
From: sources-request@genrad.UUCP
Newsgroups: mod.sources
Subject: Bourne shell history + tilde + job control + more (Part 4 of 9)
Message-ID: <882@genrad.UUCP>
Date: 10 Jun 85 11:13:31 GMT
Date-Received: 10 Jun 85 23:53:28 GMT
Sender: john@genrad.UUCP
Lines: 1861
Approved: john@genrad.UUCP

From: Arnold Robbins <gatech!arnold>

This is part 4 of 9.  It contains the diffs for the BSD Bourne shell's
man page, sh.1.

Arnold Robbins
arnold@gatech.{UUCP, CSNET}
------------------- tear here --------------------
*** ../orig.u/sh.1	Wed May 15 17:25:17 1985
--- sh.1	Wed Jun  5 11:10:39 1985
***************
*** 1,4
! .TH SH 1 "7 February 1983"
  .SH NAME
  sh, for, case, if, while, \fB:\fP, \fB.\fP, break, continue, cd, eval, exec, exit, export, login, read, readonly, set, shift, times, trap, umask, wait \- command language
  .SH SYNOPSIS

--- 1,4 -----
! .TH SH 1 "BRL + GT Modifications"
  .SH NAME
  sh \- shell, the standard command programming language
  .SH SYNOPSIS
***************
*** 1,6
  .TH SH 1 "7 February 1983"
  .SH NAME
! sh, for, case, if, while, \fB:\fP, \fB.\fP, break, continue, cd, eval, exec, exit, export, login, read, readonly, set, shift, times, trap, umask, wait \- command language
  .SH SYNOPSIS
  .B sh
  [

--- 1,6 -----
  .TH SH 1 "BRL + GT Modifications"
  .SH NAME
! sh \- shell, the standard command programming language
  .SH SYNOPSIS
  .B sh
  [
***************
*** 4,10
  .SH SYNOPSIS
  .B sh
  [
! .B \-ceiknrstuvx
  ] [ arg ] ...
  .ds OK [\|
  .ds CK \|]

--- 4,10 -----
  .SH SYNOPSIS
  .B sh
  [
! .B \-ceiknrqstuvxEHIJ
  ] [ arg ] ...
  .ds OK [\|
  .ds CK \|]
***************
*** 16,22
  .I Sh
  is a command programming language that executes commands read from a terminal
  or a file.  See
! .B invocation
  for the meaning of arguments to the shell.
  .PP
  .B Commands.

--- 16,23 -----
  .I Sh
  is a command programming language that executes commands read from a terminal
  or a file.  See
! .I Invocation
! below
  for the meaning of arguments to the shell.
  .SS Commands.
  A
***************
*** 18,26
  or a file.  See
  .B invocation
  for the meaning of arguments to the shell.
! .PP
! .B Commands.
! .br
  A
  .I simple-command
  is a sequence of non blank

--- 19,25 -----
  .I Invocation
  below
  for the meaning of arguments to the shell.
! .SS Commands.
  A
  .I simple-command
  is a sequence of non blank
***************
*** 37,43
  The
  .I value
  of a simple-command is its exit status
! if it terminates normally or 200+\fIstatus\fP if it terminates abnormally (see
  .IR sigvec (2)
  for a list of status values).
  .LP

--- 36,42 -----
  The
  .I value
  of a simple-command is its exit status
! if it terminates normally or (octal) 200+\fIstatus\fP if it terminates abnormally (see
  .IR sigvec (2)
  for a list of status values).
  .PP
***************
*** 40,46
  if it terminates normally or 200+\fIstatus\fP if it terminates abnormally (see
  .IR sigvec (2)
  for a list of status values).
! .LP
  A
  .I pipeline
  is a sequence of one or more

--- 39,45 -----
  if it terminates normally or (octal) 200+\fIstatus\fP if it terminates abnormally (see
  .IR sigvec (2)
  for a list of status values).
! .PP
  A
  .I pipeline
  is a sequence of one or more
***************
*** 46,52
  is a sequence of one or more
  .I commands
  separated by
! .B \(or.
  The standard output of each command but the last is connected by a
  .IR pipe (2)
  to the standard input of the next command.

--- 45,52 -----
  is a sequence of one or more
  .I commands
  separated by
! .B \(or
! (or, for historical compatibility, by \fB^\fP).
  The standard output of each command but the last is connected by a
  .IR pipe (2)
  to the standard input of the next command.
***************
*** 52,58
  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.
! .LP
  A
  .I list
  is a sequence of one or more

--- 52,58 -----
  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.
! .PP
  A
  .I list
  is a sequence of one or more
***************
*** 60,66
  separated by
  .BR ; ,
  .BR & ,
! .B &&
  or
  .B \(or\|\(or
  and optionally terminated by

--- 60,66 -----
  separated by
  .BR ; ,
  .BR & ,
! .B && ,
  or
  .B \(or\|\(or
  and optionally terminated by
***************
*** 67,72
  .B ;
  or
  .BR & .
  .B ;
  and
  .B &

--- 67,73 -----
  .B ;
  or
  .BR & .
+ Of these four symbols,
  .B ;
  and
  .B &
***************
*** 90,96
  returns a zero (non zero) value.  Newlines may appear in a
  .I list,
  instead of semicolons, to delimit commands.
! .LP
  A
  .I command
  is either a simple-command or one of the following.

--- 91,97 -----
  returns a zero (non zero) value.  Newlines may appear in a
  .I list,
  instead of semicolons, to delimit commands.
! .PP
  A
  .I command
  is either a simple-command or one of the following.
***************
*** 143,148
  .B else
  .I list
  is executed.
  .TP
  \fBwhile \fIlist\fR \*(OK\fBdo \fIlist\fR\*(CK \fBdone\fR
  A

--- 144,158 -----
  .B else
  .I list
  is executed.
+ If no
+ .B else
+ .I list
+ or
+ .B then
+ .I list
+ is executed, then the
+ .B if
+ command returns a zero exit status.
  .TP
  \fBwhile \fIlist\fR \*(OK\fBdo \fIlist\fR\*(CK \fBdone\fR
  A
***************
*** 171,177
  .BI { " list " }
  .I list
  is simply executed.
! .LP
  The following words are only recognized as the first word of a command
  and when not quoted.
  .IP

--- 181,187 -----
  .BI { " list " }
  .I list
  is simply executed.
! .PP
  The following words are only recognized as the first word of a command
  and when not quoted.
  .IP
***************
*** 177,185
  .IP
  .B
  if then else elif fi case in esac for while until do done { }
! .PP
! .B Command substitution.
! .br
  The standard output from a command enclosed in a pair of back quotes 
  .RB ( \`\|\` )
  may be used as part or all of a word; trailing newlines are removed.

--- 187,198 -----
  .IP
  .B
  if then else elif fi case in esac for while until do done { }
! .SS Comments
! A word beginning with
! .B #
! causes that word and all the following characters up to a new-line
! to be ignored.
! .SS Command substitution.
  The standard output from a command enclosed in a pair of back quotes 
  .RB ( \`\|\` )
  may be used as part or all of a word; trailing newlines are removed.
***************
*** 183,191
  The standard output from a command enclosed in a pair of back quotes 
  .RB ( \`\|\` )
  may be used as part or all of a word; trailing newlines are removed.
! .PP
! .B Parameter substitution.
! .br
  The character
  .B $
  is used to introduce substitutable parameters.

--- 196,202 -----
  The standard output from a command enclosed in a pair of back quotes 
  .RB ( \`\|\` )
  may be used as part or all of a word; trailing newlines are removed.
! .SS Parameter substitution.
  The character
  .B $
  is used to introduce substitutable parameters.
***************
*** 194,200
  Variables may be set by writing
  .IP
  .IB name = value
! [
  .IB name = value
  ] ...
  .TP

--- 205,211 -----
  Variables may be set by writing
  .IP
  .IB name = value
! \*(OK
  .IB name = value
  \*(CK ...
  .PP
***************
*** 196,202
  .IB name = value
  [
  .IB name = value
! ] ...
  .TP
  $\fB\|{\fIparameter\fB\|}\fR
  A

--- 207,216 -----
  .IB name = value
  \*(OK
  .IB name = value
! \*(CK ...
! .PP
! Pattern matching is not performed on
! .IR value .
  .TP
  $\fB\|{\fIparameter\fB\|}\fR
  A
***************
*** 205,211
  .IR name ),
  a digit, or any of the characters
  .B
! * @ # ? \- $ !\|.
  The value, if any, of the parameter is substituted.
  The braces are required only when
  .I parameter

--- 219,225 -----
  .IR name ),
  a digit, or any of the characters
  .B
! * @ # ? \- $ + !\|.
  The value, if any, of the parameter is substituted.
  The braces are required only when
  .I parameter
***************
*** 210,216
  The braces are required only when
  .I parameter
  is followed by a letter, digit, or underscore
! that is not to be interpreted as part of its name.  If
  .I parameter
  is a digit, it is a positional parameter.  If
  .I parameter

--- 224,234 -----
  The braces are required only when
  .I parameter
  is followed by a letter, digit, or underscore
! that is not to be interpreted as part of its name.
! A
! .I name
! must begin with a letter or underscore.
! If
  .I parameter
  is a digit, it is a positional parameter.  If
  .I parameter
***************
*** 253,259
  is set, substitute
  .I word;
  otherwise substitute nothing.
! .LP
  In the above
  .I word
  is not evaluated unless it is to be used as the substituted string.

--- 271,277 -----
  is set, substitute
  .I word;
  otherwise substitute nothing.
! .PP
  In the above
  .I word
  is not evaluated unless it is to be used as the substituted string.
***************
*** 282,287
  .B $
  The process number of this shell.
  .TP
  .B !
  The process number of the last background command invoked.
  .PD

--- 300,317 -----
  .B $
  The process number of this shell.
  .TP
+ .B +
+ The process number of the partent of this shell.  In particular,
+ the value of
+ .B $+
+ will track the value of the
+ .IR getppid (2)
+ system call.  I.e. if
+ .I init
+ should inherit this shell,
+ .B $+
+ will become 1.
+ .TP
  .B !
  The process number of the last background command invoked.
  .PD
***************
*** 286,292
  The process number of the last background command invoked.
  .PD
  .RE
! .LP
  The following
  .I parameters
  are used but not set by the shell.

--- 316,322 -----
  The process number of the last background command invoked.
  .PD
  .RE
! .PP
  The following
  .I parameters
  are used but not set by the shell.
***************
*** 302,308
  .B
  .SM PATH
  The search path for commands (see
! .BR execution ).
  .TP
  .B
  .SM MAIL

--- 332,339 -----
  .B
  .SM PATH
  The search path for commands (see
! .I Execution
! below).
  .TP
  .B
  .SM MAIL
***************
*** 325,330
  .BR tab ,
  and
  .BR newline .
  .PD
  .RE
  .PP

--- 356,366 -----
  .BR tab ,
  and
  .BR newline .
+ .TP
+ .B HISTFILE
+ The file where command history is saved across login sessions.
+ The default value is
+ .BR $HOME/.history .
  .PD
  .RE
  .SS Tilde Substitution
***************
*** 327,332
  .BR newline .
  .PD
  .RE
  .PP
  .B Blank interpretation.
  .br

--- 363,375 -----
  .BR $HOME/.history .
  .PD
  .RE
+ .SS Tilde Substitution
+ An unquoted tilde character
+ .RB ( ~ )
+ will cause the shell to attempt a tilde substituion.  Tilde substitutions
+ are used to automatically determine home directories.  Both the current
+ user's home directory, and the home directory of any other user on
+ the system may be found.
  .PP
  A
  .B ~
***************
*** 328,336
  .PD
  .RE
  .PP
! .B Blank interpretation.
! .br
! After parameter and command substitution,
  any results of substitution are scanned for internal field separator
  characters (those found in
  .SM

--- 371,588 -----
  user's home directory, and the home directory of any other user on
  the system may be found.
  .PP
! A
! .B ~
! by itself is equivalent to using
! .BR \s-1$HOME\s+1 .
! E.g.
! .B ~/bin
! is the same as saying
! .BR \s-1$HOME\s+1/bin .
! The notation
! .B ~person
! will cause the shell to look up
! .BR person 's
! home directory in the
! .B /etc/passwd
! file, and substitute it in.  For example, if user
! .BR arnold 's
! home directory is
! .BR /user/arnold ,
! the shell would replace
! .BR ~arnold/bin
! with
! .BR /user/arnold/bin .
! .PP
! Tilde substitutions are recognized at the beginning of words, after
! equal signs (for shell variable assignment), in the middle of single letter
! flag arguments to commands (e.g. \fBecho \-t~arnold\fP), and after
! colons inside the
! .B
! .SM PATH
! shell parameter.
! .PP
! If
! .B /etc/passwd
! cannot be read, or if
! no user can be found to match the attempted tilde substitution,
! the text is left unmodified.
! .SS History Substitution
! When reading input from an interactive terminal, a
! .RB `` ! ''
! character, anywhere on the line,
! signals the shell that it should attempt
! to perform a history substitution.
! A history substitution is a shorthand method which allows the user
! to recall all or part of a previous command, possibly editing the
! recalled portion.
! The recalled (and possibly changed) command line is then placed into
! the current command line,
! to be passed on to the rest of the shell for normal processing.
! A history substitution takes the form:
! .PP
! .if t .RS
! \fB!\fP\^[ \fIstr\fP | \fB?\fIstr\fB?\fR | \fInum\fP ]\c
! [ \fB\(ga\fInum\fR [ \- [ \fInum\fP ] ]\c
! { \fB^\fIstr\fB^\fIstr\fB^\fR [\fBg\fP] }
! .if t .RE
! .PP
! A history substitution contains three parts;
! command selection, argument selection, and editing.
! .I Command selection
! chooses what command will be retrieved from the stored
! history.
! .I Argument selection
! chooses which arguments from that command will be extracted.
! .I Editing
! allows the user to change spelling or make a substitution.
! .PP
! The history substitution is triggered by the
! .RB `` ! '',
! and continues until another
! .RB `` ! ''
! is encountered, or until
! something that could not be part of a history substitution is seen.
! This is so that the
! history substitution will be properly concatenated with the following text.
! Whenever a history substitution is encountered and properly performed,
! the shell echoes the resulting line to the terminal and then executes the
! command.
! .PP
! History substitution occurs inside double quotes and grave accents, but will
! not occur inside single quotes.  To get a literal
! .RB `` ! ''
! character, outside of single quotes, precede it with a
! .BR \e .
! The
! .BR ? ,
! .BR \(ga ,
! and
! .B ^
! characters are treated specially by the history mechanism only when preceded
! by a
! .RB `` ! '',
! otherwise they have their normal meaning
! of ``match a single character'',
! ``enclose a command substitution'',
! and as a synonym for the \fB\(bv\fP
! character.
! .PP
! The full meaning of the history syntax is as follows:
! .RS
! .TP
! \fB!\fP\^[ \fIstr\fP | \fB?\fIstr\fB?\fR | \fInum\fP ]
! The first thing in a history substitution is
! .IR "command selection" .
! This is used to retrieve a given command line for use, or for further
! processing.  In a history command selection, \fB!\fIstr\fR
! will find the most recent command line that started with the
! characters in
! .IR str .
! \fB!?\fIstr\fB?\fR will find the most recent command line that contained
! .I str
! anywhere on the line.  It also allows
! .I str
! to contain blanks and tabs, whereas the first form does not.
! \fB!\fInum\fR allows the user to specify the number of a command, according
! to the output of the
! .B history
! command (see the section on special commands, below).
! .TP
! \fB\(ga\fInum\fR [ \- [ \fInum\fP ]
! The next portion of a history substitution is an optional
! .IR "argument selection" .
! This chooses which portions of the command are to be kept.
! History arguments are not exactly the same as the arguments the rest of
! the shell uses, since history expansion occurs before argument collection.
! Arguments in this context are blank or tab separated words on the command line.
! Single or double quoted strings, strings inside grave accents, shell regular
! expressions, commands in parentheses (which get executed in a subshell),
! and commands enclosed in braces,
! are all treated as single arguments for the history mechanism, even though
! they may have white space in them.
! .sp
! Arguments are numbered from zero, starting at the leftmost portion of the
! line.  In an argument selection, \fB\(ga\fInum\fR specifies that only argument
! .I num
! is to be extracted and kept for further processing or use, and the rest
! of the command line is to be dropped.
! \fB\(ga\fInum\fB\-\fInum\fR
! specifies that the arguments from the first
! .I num
! to the last
! .I num
! are to be kept. In place of any
! .IR num ,
! .B $
! may be specified to obtain the last argument on the line.
! The form \fB\(ga\-\fInum\fR is a shorthand for \fB\(ga\fP1\fB\-\fInum\fR
! and
! \fB\(ga\fInum\fB\-\fR
! is a short form for
! \fB\(ga\fInum\fB\-$\fR.
! Finally, the notation
! \fB\(ga\-\fP
! indicates all the arguments.  That is, \fB\(ga\-\fP implies
! \fB\(ga1\-$\fP.
! .TP
! \fB^\fIstr\fB^\fIstr\fB^\fR [\fBg\fP]
! The last portion of a history substitution is also optional, and is the
! .I editing
! phase.  This allows the remaining portions of the retrieved
! command line to modified, like the substitute command in
! .IR ed (1),
! although in a much more limited fashion.
! In the history mechanism,
! .I str
! is not a regular expression, as in
! .IR ed,
! but just a simple string.
! The history mechanism does not recognize
! either the shell's pattern matching characters or the editor's
! regular expression characters.
! Each substitution happens only once on a line, unless a trailing ``g''
! is appended to the substitution.  In this case, the substitution occurs
! globally (everywhere) on the line.
! Substitutions may be strung together,
! so that more than one can be done at once.
! The trailing ``g'' may be in either upper or lower case.
! .RE
! .PP
! Some examples of history substitution are given below.
! Should a history substitution fail, the errant command will
! .I not
! be added to the history buffers.
! .PP
! The history mechanism recognizes lines that end with unbalanced quotes.
! When the quotes are balanced on the next line(s), 
! It will join this line with the one that opened the quotes, keeping the
! embedded newline(s). So, e.g.,
! .RS
! .sp
! .nf
! .RB "$ " "echo 'open"
! .RB "> " "close'"
! .fi
! .RE
! .sp
! will be saved as one history ``event.''
! This does
! .I not
! extend to other shell constructs, like balancing parentheses across
! newlines.
! .PP
! The history mechanism keeps a maximum of
! 256
! stored commands at any one time, and the total text of the
! stored history may occupy no more than
! 4096
! characters.
! Experience indicates that it is not necessary to store more than this,
! and the extra history buffers should not make the shell too large for
! machines with small address spaces (e.g. PDP-11's).
! .SS Blank Interpretation
! After history, tilde, parameter and command substitution,
  any results of substitution are scanned for internal field separator
  characters (those found in
  .SM
***************
*** 340,348
  Implicit null arguments (those resulting from
  .I parameters
  that have no values) are removed.
! .PP
! .B File name generation.
! .br
  Following substitution, each command word is scanned for the characters
  .BR * ,
  .B ?

--- 592,598 -----
  Implicit null arguments (those resulting from
  .I parameters
  that have no values) are removed.
! .SS File name generation.
  Following substitution, each command word is scanned for the characters
  .BR * ,
  .B ?
***************
*** 370,376
  Matches any one of the characters enclosed.
  A pair of characters separated by
  .B \-
! matches any character lexically between the pair.
  .PD
  .PP
  .B Quoting.

--- 620,636 -----
  Matches any one of the characters enclosed.
  A pair of characters separated by
  .B \-
! matches any character lexically between the pair, inclusive.
! If the first character floolowing the opening
! .RB `` \*(OK ''
! is a
! .RB `` ! ''
! then any character not enclosed is matched.
! Note that when typing input from the terminal, the
! .RB `` ! ''
! should be preceded by a
! .BR \e ,
! so that the shell does not attempt to perform a history substitution.
  .PD
  .SS Quoting.
  The following characters have a special meaning to the shell
***************
*** 372,380
  .B \-
  matches any character lexically between the pair.
  .PD
! .PP
! .B Quoting.
! .br
  The following characters have a special meaning to the shell
  and cause termination of a word unless quoted.
  .LP

--- 632,638 -----
  .BR \e ,
  so that the shell does not attempt to perform a history substitution.
  .PD
! .SS Quoting.
  The following characters have a special meaning to the shell
  and cause termination of a word unless quoted.
  .LP
***************
*** 389,395
  is ignored.
  All characters enclosed between a pair of quote marks (\fB\'\|\'\fP),
  except a single quote, are quoted.  Inside double quotes (\fB"\|"\fP)
! parameter and command substitution occurs and
  .B
  \\
  quotes the characters

--- 647,653 -----
  is ignored.
  All characters enclosed between a pair of quote marks (\fB\'\|\'\fP),
  except a single quote, are quoted.  Inside double quotes (\fB"\|"\fP)
! history, parameter, and command substitution occurs and
  .B
  \\
  quotes the characters
***************
*** 394,400
  \\
  quotes the characters
  .B
! \\ \' "
  and
  .BR $ \|.
  .LP

--- 652,658 -----
  \\
  quotes the characters
  .B
! \\ \' " !
  and
  .BR $ \|.
  .PP
***************
*** 397,403
  \\ \' "
  and
  .BR $ \|.
! .LP
  .B
  "$*"
  is equivalent to

--- 655,661 -----
  \\ \' " !
  and
  .BR $ \|.
! .PP
  .B
  "$*"
  is equivalent to
***************
*** 412,421
  .SM
  .B
  "$1" "$2" ... .
! .PP
! .B Prompting.
! .br
! When used interactively, the shell prompts with the value of
  .SM
  PS1
  before reading a command.

--- 670,678 -----
  .SM
  .B
  "$1" "$2" ... .
! .SS Prompting
! When used interactively,
! the shell prompts with the value of
  .SM
  .B PS1
  before reading a command.
***************
*** 417,423
  .br
  When used interactively, the shell prompts with the value of
  .SM
! PS1
  before reading a command.
  If at any time a newline is typed and further input is needed
  to complete a command, the secondary prompt

--- 674,680 -----
  When used interactively,
  the shell prompts with the value of
  .SM
! .B PS1
  before reading a command.
  If the user is super-user and
  .SM
***************
*** 419,425
  .SM
  PS1
  before reading a command.
! If at any time a newline is typed and further input is needed
  to complete a command, the secondary prompt
  .RB ( \s-2$PS2\s0 )
  is issued.

--- 676,693 -----
  .SM
  .B PS1
  before reading a command.
! If the user is super-user and
! .SM
! .B PS1
! is not set to
! .RB `` "# \|" ''
! already, the
! .SM
! .B PS1
! prompt is followed by
! .RB `` "# \|" ''
! as a BRL-supplied safety reminder.
! If at any time a new-line is typed and further input is needed
  to complete a command, the secondary prompt
  (i.e., the value of
  .BR \s-1PS2\s+1 )
***************
*** 421,427
  before reading a command.
  If at any time a newline is typed and further input is needed
  to complete a command, the secondary prompt
! .RB ( \s-2$PS2\s0 )
  is issued.
  .PP
  .B Input output.

--- 689,696 -----
  as a BRL-supplied safety reminder.
  If at any time a new-line is typed and further input is needed
  to complete a command, the secondary prompt
! (i.e., the value of
! .BR \s-1PS2\s+1 )
  is issued.
  .PP
  Many people like to have the shell provide them with useful information
***************
*** 424,431
  .RB ( \s-2$PS2\s0 )
  is issued.
  .PP
! .B Input output.
! .br
  Before 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 simple-command

--- 693,752 -----
  .BR \s-1PS2\s+1 )
  is issued.
  .PP
! Many people like to have the shell provide them with useful information
! in their prompt.  To accomadate this, the shell will recognize special
! sequences of characters in the value of
! .BR PS1 ,
! and substitute the appropriate information for them.
! The special sequences and what they signify are:
! .RS
! .TP
! .B %e
! Place the current event number (as defined by the
! .B history
! command) into the prompt.
! If history evaluation has been turned off (via
! .BR "set -H" ),
! no number will be substituted in (i.e. the
! .B %e
! will be removed).
! .TP
! .B %h
! Place the machine's host name into the prompt.  The host name is usually
! the name by which the machine is known to the outside world for electronic
! mail addressing.
! .TP
! .B %l
! Place the user's login name into the prompt.
! The login name selected is the first entry in the
! .B /etc/passwd
! file whose
! .I uid
! matches the value of the
! .IR getuid (2)
! system call.
! This will be a problem on systems where multiple users share the same
! user-id number.
! .TP
! .B %t
! Place the current time of day, in the form \s-1HH:MM\s+1 into the prompt.
! The time is on a 24 hour clock, i.e. 1:30 in the afternoon will be 13:30.
! .TP
! .BI % x
! Place the character
! .I x
! into the prompt.
! If the user wishes to put a literal
! .B %
! into the prompt, then
! .B PS1
! should have
! .B %%
! in it.
! .RE
! .PP
! Some of these facilities are of more use than others.
! .SS Input/Output.
  Before 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 simple-command
***************
*** 458,464
  If the file exists, output is appended (by seeking to the end);
  otherwise the file is created.
  .TP
! \*(LT\*(LT\fI\|word\fP
  The shell input is read up to a line the same as
  .IR word ,
  or end of file.

--- 779,785 -----
  If the file exists, output is appended (by seeking to the end);
  otherwise the file is created.
  .TP
! \*(LT\*(LT\*(OK\fB\-\fP\*(CK\fI\|word\fP
  The shell input is read up to a line the same as
  .IR word ,
  or end of file.
***************
*** 477,482
  \\ $ \'
  and the first character of
  .I word.
  .TP
  \*(LT\|&\|\fIdigit\fP
  The standard input is duplicated from file descriptor

--- 798,810 -----
  \\ $ \'
  and the first character of
  .I word.
+ If
+ .B \-
+ is appended to \*(LT\|\*(LT, all leading tabs are stripped from
+ .I word
+ and from the document.
+ History substitution is turned off
+ while processing the document.
  .TP
  \*(LT\|&\|\fIdigit\fP
  The standard input is duplicated from file descriptor
***************
*** 488,493
  \*(LT\|&\|\-
  The standard input is closed.
  Similarly for the standard output using \*(GT\|.
  .PD
  .LP
  If one of the above is preceded by a digit, the

--- 816,829 -----
  \*(LT\|&\|\-
  The standard input is closed.
  Similarly for the standard output using \*(GT\|.
+ .TP
+ \*(LT\|\*(GTword
+ Use file
+ .I word
+ for standard input (file descriptor 0),
+ but open it for reading
+ .I and
+ writing.
  .PD
  .LP
  If one of the above is preceded by a digit, the
***************
*** 498,504
  .LP
  creates file descriptor 2 to be a duplicate
  of file descriptor 1.
! .LP
  If a command is followed by
  .B &
  then the default standard input for the command is the empty file

--- 834,840 -----
  .LP
  creates file descriptor 2 to be a duplicate
  of file descriptor 1.
! .PP
  If a command is followed by
  .B &
  then the default standard input for the command is the empty file
***************
*** 506,514
  Otherwise, the environment for the execution of a command contains the
  file descriptors of the invoking shell as modified by input
  output specifications.
! .PP
! .B Environment.
! .br
  The 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
  .IR execve (2)

--- 842,848 -----
  Otherwise, the environment for the execution of a command contains the
  file descriptors of the invoking shell as modified by input
  output specifications.
! .SS Environment.
  The 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
  .IR execve (2)
***************
*** 531,537
  plus any modifications or additions, all of which must be noted in
  .B export
  commands.
! .LP
  The environment for any
  .I simple-command
  may be augmented by prefixing it with one or more assignments to

--- 865,871 -----
  plus any modifications or additions, all of which must be noted in
  .B export
  commands.
! .PP
  The environment for any
  .I simple-command
  may be augmented by prefixing it with one or more assignments to
***************
*** 554,562
  set \-k
  echo a=b c
  .fi
! .PP
! .B Signals.
! .br
  The INTERRUPT and QUIT signals for an invoked
  command are ignored if the command is followed by
  .BR & ;

--- 888,894 -----
  set \-k
  echo a=b c
  .fi
! .SS Signals.
  The INTERRUPT and QUIT signals for an invoked
  command are ignored if the command is followed by
  .BR & ;
***************
*** 562,571
  .BR & ;
  otherwise signals have the values inherited by the shell from its parent.
  (But see also
! .BR trap. )
! .PP
! .B Execution.
! .br
  Each time a command is executed the above substitutions are carried out.
  Except for the 'special commands' listed below a new process is created and
  an attempt is made to execute the command via an

--- 894,904 -----
  .BR & ;
  otherwise signals have the values inherited by the shell from its parent.
  (But see also
! .BR trap .)
! When job control is enabled,
! .SM SIGTSTP
! causes a foreground command to be stopped.
! .SS Execution.
  Each time a command is executed the above substitutions are carried out.
  Except for the 'special commands' listed below a new process is created and
  an attempt is made to execute the command via an
***************
*** 570,576
  Except for the 'special commands' listed below a new process is created and
  an attempt is made to execute the command via an
  .IR execve (2).
! .LP
  The shell parameter
  .B
  .SM $PATH

--- 903,909 -----
  Except for the 'special commands' listed below a new process is created and
  an attempt is made to execute the command via an
  .IR execve (2).
! .PP
  The shell parameter
  .B
  .SM $PATH
***************
*** 586,594
  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.
! .PP
! .B Special commands.
! .br
  The following commands are executed in the shell process
  and except where specified
  no input output redirection is permitted for such commands.

--- 919,925 -----
  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.
! .SS Special commands.
  The following commands are executed in the shell process
  and except where specified
  no input output redirection is permitted for such commands.
***************
*** 595,600
  .TP
  .B :
  No effect; the command does nothing.
  .PD 0
  .TP
  .BI . \ file

--- 926,932 -----
  .TP
  .B :
  No effect; the command does nothing.
+ A zero exit code is returned.
  .PD 0
  .TP
  .BI . \ file
***************
*** 662,667
  of subsequently-executed commands.
  If no arguments are given, a list of exportable names is printed.
  .TP
  \fBlogin\fR \*(OK\fIarg\fR ...\*(CK
  Equivalent to 'exec login arg ...'.
  .TP

--- 994,1042 -----
  of subsequently-executed commands.
  If no arguments are given, a list of exportable names is printed.
  .TP
+ \fBhistory\fP \*(OK \fB\-irs\fP \*(OK \fIfilename\fP \*(CK \*(CK
+ The \fBhistory\fP command, with no arguments, will print all the commands that
+ are currently saved in the shell's history buffers.  As new commands are
+ executed, and space in the buffers runs out, old commands will be deleted.  The
+ .B history
+ commands prints out the stored commands with sequence numbers.  Negative
+ numbered commands, through command number zero, are commands that were
+ retrieved from the saved history file.  Commands starting at one were
+ entered during the current login session.
+ If a saved command contains embedded newlines, these will be printed out
+ as the sequence
+ .BR \en ,
+ so that individual command stay on one line.
+ .sp
+ The \fBhistory\fP command takes two optional arguments.  If the first
+ argument is \fB\-s\fP, the shell will save its current history buffers
+ in the file named as the third argument. If no file is given, it will
+ use the value of
+ .BR \s-1HISTFILE\s+1 .
+ .sp
+ Similarly, if the first argument is \fB\-r\fP, the shell will reset its
+ history buffers from the saved history in the file given as the third argument.
+ Again, if no file name is given,
+ .B \s-1$HISTFILE\s+1
+ will be used.
+ .sp
+ The command
+ .B history -i
+ will cause the shell to reinitialize its history buffers.  In other words,
+ all the shell's saved history will be thrown away, and the shell will
+ start from scratch.
+ .sp
+ The \fBhistory\fP command will have absolutely no effect at all if input
+ is not coming from a terminal.  I.e., inside shell files, the
+ .B history
+ command is effectively a null operation.
+ .sp
+ The
+ .B history
+ command will always have an exit status of 1 inside a shell file.
+ If input is coming from a terminal, then the exit status wil be 0
+ if the command succeeds, 1 otherwise.
+ .TP
  \fBlogin\fR \*(OK\fIarg\fR ...\*(CK
  Equivalent to 'exec login arg ...'.
  .TP
***************
*** 678,684
  by subsequent assignment.
  If no arguments are given, a list of all readonly names is printed.
  .TP
! \fBset\fR \*(OK\fB\-eknptuvx\fR \*(OK\fIarg \fR...\*(CK\*(CK
  .RS
  .PD 0
  .TP 3m

--- 1053,1059 -----
  by subsequent assignment.
  If no arguments are given, a list of all readonly names is printed.
  .TP
! \fBset\fR \*(OK\fB\-eknptuvxEHIJ\fR \*(OK\fIarg \fR...\*(CK\*(CK
  .RS
  .PD 0
  .TP 3m
***************
*** 704,709
  .B \-x
  Print commands and their arguments as they are executed.
  .TP
  .B \-
  Turn off the
  .B \-x

--- 1079,1128 -----
  .B \-x
  Print commands and their arguments as they are executed.
  .TP
+ .B \-E
+ Prevents an EOT
+ .RI ( control-D\^ )
+ from terminating an interactive shell.
+ Added by BRL mostly for use in
+ .IR .profile\^ s
+ to avoid accidental logout.
+ .TP
+ .B \-H
+ Disable history processing.  If the shell is invoked with this option,
+ it will not bother trying to restore its saved history from the
+ contents of
+ .BR \s-1$HISTFILE\s+1 .
+ While this flag is in effect, the shell will not save any commands in
+ its history buffers.
+ The sequence
+ .B %e
+ in the value of
+ .B \s-1PS1\s+1
+ will also have no effect on the generated prompt string.
+ If
+ .B set +H
+ is used to turn history processing back on, the shell will start saving
+ subsequent commands from that point on.
+ .TP
+ .B \-I
+ (BRL addition)
+ Prints a resource usage summary
+ (system plus user time, blocks input and output, page reclaims and faults)
+ for each command after it terminates.
+ .TP
+ .B \-J
+ (BRL addition)
+ Enables ``job control'' features (see below).
+ .TP
+ .B \-\-
+ Do not change any of the flags; useful in setting
+ .B $1
+ to
+ .BR \- .
+ .PP
+ Using
+ .B \+
+ rather than
  .B \-
  causes these flags to be turned off.
  .PP
***************
*** 705,717
  Print commands and their arguments as they are executed.
  .TP
  .B \-
! Turn off the
! .B \-x
! and
! .B \-v
! options.
! .PD
! .LP
  These flags can also be used upon invocation of the shell.
  The current set of flags may be found in
  .BR $\- .

--- 1124,1131 -----
  .B \+
  rather than
  .B \-
! causes these flags to be turned off.
! .PP
  These flags can also be used upon invocation of the shell.
  The current set of flags may be found in
  .BR $\- .
***************
*** 715,721
  These flags can also be used upon invocation of the shell.
  The current set of flags may be found in
  .BR $\- .
! .LP
  Remaining arguments are positional
  parameters and are assigned, in order, to
  .SM

--- 1129,1135 -----
  These flags can also be used upon invocation of the shell.
  The current set of flags may be found in
  .BR $\- .
! .PP
  Remaining arguments are positional
  parameters and are assigned, in order, to
  .SM
***************
*** 743,749
  (Note that
  .I arg
  is scanned once when the trap is set and once when the trap is taken.)
! Trap commands are executed in order of signal number.  If
  .I arg
  is absent, all trap(s)
  .I n

--- 1157,1168 -----
  (Note that
  .I arg
  is scanned once when the trap is set and once when the trap is taken.)
! Trap commands are executed in order of signal number.
! Any attempt to set a trap on a signal that
! was ignored on entry to the current shell
! is ineffective.
! An attempt to trap on signal 11 (memory fault) produces an error.
! If
  .I arg
  is absent, all trap(s)
  .I n
***************
*** 778,788
  is not given, all currently active child processes are waited for.
  The return code from this command is that of the process waited for.
  .PD
! .LP
! .PP
! .B Invocation.
! .br
! If the first character of argument zero is
  .BR \- ,
  commands are read from
  .BR \s-2$HOME\s0/.\|profile ,

--- 1197,1207 -----
  is not given, all currently active child processes are waited for.
  The return code from this command is that of the process waited for.
  .PD
! .SS Invocation
! If the shell is invoked through
! .IR execve (2)
! and the first character of argument zero
! is
  .BR \- ,
  commands are initially read from
  .BR \s-1$HOME\s+1/.profile ,
***************
*** 784,791
  .br
  If the first character of argument zero is
  .BR \- ,
! commands are read from
! .BR \s-2$HOME\s0/.\|profile ,
  if such a file exists.
  Commands are then read as described below.
  The following flags are interpreted by the shell when it is invoked.

--- 1203,1210 -----
  and the first character of argument zero
  is
  .BR \- ,
! commands are initially read from
! .BR \s-1$HOME\s+1/.profile ,
  if such a file exists.
  Next, whether or not the first character of argument zero was a
  .BR \- ,
***************
*** 787,793
  commands are read from
  .BR \s-2$HOME\s0/.\|profile ,
  if such a file exists.
! Commands are then read as described below.
  The following flags are interpreted by the shell when it is invoked.
  .PD 0
  .TP 11n

--- 1206,1231 -----
  commands are initially read from
  .BR \s-1$HOME\s+1/.profile ,
  if such a file exists.
! Next, whether or not the first character of argument zero was a
! .BR \- ,
! and no matter how the shell was invoked,
! the shell will read commands from the file
! .BR \s-1$HOME\s+1/.shrc ,
! if it exists.
! Then, if the shell is interactive, is not a forked subshell,
! and the
! .B \-H
! flag is not in effect,
! it will attempt to restore its saved history from
! .BR \s-1$HISTFILE\s+1 .
! Thereafter, commands are read as described below, which
! is also the case when the shell is invoked as
! .BR /bin/sh .
! If any character of argument zero past the last slash (if any) is
! .BR j ,
! the
! .B \-J
! (job control) flag is automatically set.
  The following flags are interpreted by the shell when it is invoked.
  .PD 0
  .TP 11n
***************
*** 820,825
  .B wait
  is interruptible).
  In all cases SIGQUIT is ignored by the shell.
  .PD
  .LP
  The remaining flags and arguments are described under the

--- 1258,1279 -----
  .B wait
  is interruptible).
  In all cases SIGQUIT is ignored by the shell.
+ .TP
+ .B \-r
+ If the
+ .B \-r
+ flag is present, the shell is a restricted shell.
+ .TP
+ .B \-q
+ If the
+ .B \-q
+ flag is present, the shell will do a ``quick'' startup.
+ This means that the shell will
+ .I not
+ read the contents of the
+ .B \s-1$HOME\s+1/.shrc
+ file.
+ The shell will also not try to read this file if it is a restricted shell.
  .PD
  .PP
  The remaining flags and arguments are described under the
***************
*** 821,827
  is interruptible).
  In all cases SIGQUIT is ignored by the shell.
  .PD
! .LP
  The remaining flags and arguments are described under the
  .B set
  command.

--- 1275,1281 -----
  file.
  The shell will also not try to read this file if it is a restricted shell.
  .PD
! .PP
  The remaining flags and arguments are described under the
  .B set
  command.
***************
*** 825,830
  The remaining flags and arguments are described under the
  .B set
  command.
  .SH FILES
  .RB $HOME/ . \^profile
  .br

--- 1279,1366 -----
  The remaining flags and arguments are described under the
  .B set
  command.
+ .SS Job Control.
+ Job control features are enabled by the
+ .B \-J
+ flag.
+ When job control is enabled,
+ background commands and foreground commands that have been stopped
+ (usually by a \s-1SIGTSTP\s0 signal generated by typing
+ .IR ^Z\^ )
+ are placed into separate individual
+ .IR "process groups"\^ .
+ The following commands are used to manipulate these process groups:
+ .PP
+ .PD 0
+ .TP
+ \f3jobs\fP
+ Display information about the controlled jobs.
+ The job number is given in brackets,
+ followed by a plus sign if it is the ``current job'',
+ then the process group number for the job,
+ then the command.
+ .TP
+ \f3fg\fP \*(OK \f2n\^\fP \*(CK
+ Resume the stopped foreground job in the foreground.
+ If the process group
+ .I n\^
+ is not specified then the ``current job'' is resumed.
+ .TP
+ \f3bg\fP \*(OK \f2n\^\fP \*(CK
+ Resume the stopped foreground job in the background.
+ If the process group
+ .I n\^
+ is not specified then the ``current job'' is resumed.
+ .TP
+ .B suspend
+ Suspend the shell process itself in the background.
+ The shell will complain
+ if it is a login shell, and will not suspend itself.
+ Otherwise, it does not matter whether or not job control is enabled.
+ .PD
+ .PP
+ With job control enabled,
+ there are the following additional substitutable parameters:
+ .PP
+ .PD 0
+ .TP
+ .BR %%
+ If there is a ``current job'',
+ then this expression is replaced by
+ its process group number.
+ .TP
+ .BI % n\^
+ If the specified job number is one of the known jobs,
+ then this expression is replaced by
+ the corresponding process group number.
+ .SS Saving and Restoring History
+ When an interactive shell starts up, if the
+ .B \-H
+ flag is not in effect, it will attempt to read the contents of
+ .B \s-1$HISTFILE\s+1
+ into its history buffers.  This allows the user to recall commands
+ executed during a previous login session.
+ When the shell exits or executes an
+ .B exec
+ (again, if
+ .B \-H
+ is not in effect), it will attempt to write its current history
+ buffers into
+ .BR \s-1$HISTFILE\s+1 ,
+ for use in a future login session.
+ .PP
+ The
+ .B history
+ command allows the user to save the current history buffers into
+ a file of his or her own choosing, or to restore them from a given file.
+ If
+ .B \-H
+ has been set, the
+ .B history
+ command will give a warning that history processing is not
+ available, and will
+ .I not
+ save or restore the shell's history buffers.
  .SH FILES
  .RB $HOME/ . \^profile
  .br
***************
*** 828,833
  .SH FILES
  .RB $HOME/ . \^profile
  .br
  /tmp/sh*
  .br
  /dev/null

--- 1364,1371 -----
  .SH FILES
  .RB $HOME/ . \^profile
  .br
+ .RB $HOME/ . \^shrc
+ .br
  /tmp/sh*
  .br
  /dev/null
***************
*** 833,838
  /dev/null
  .SH SEE ALSO
  csh(1),
  test(1),
  execve(2),
  environ(7)

--- 1371,1377 -----
  /dev/null
  .SH SEE ALSO
  csh(1),
+ ed(1),
  test(1),
  execve(2),
  getppid(2),
***************
*** 835,840
  csh(1),
  test(1),
  execve(2),
  environ(7)
  .SH DIAGNOSTICS
  Errors detected by the shell, such as syntax errors cause the shell

--- 1374,1380 -----
  ed(1),
  test(1),
  execve(2),
+ getppid(2),
  environ(7)
  .SH DIAGNOSTICS
  Errors detected by the shell, such as syntax errors cause the shell
***************
*** 849,851
  process invoked by &, the shell gets mixed up about naming the input document.
  A garbage file /tmp/sh* is created, and the shell complains about
  not being able to find the file by another name.

--- 1389,1505 -----
  process invoked by &, the shell gets mixed up about naming the input document.
  A garbage file /tmp/sh* is created, and the shell complains about
  not being able to find the file by another name.
+ .SH PYRAMID SPECIFIC
+ .PP
+ On computers manufactured by the Pyramid Corporation, which support
+ both the University of California at Berkeley 4.2BSD version of \s-1UNIX\s+1,
+ and the AT&T System V version of \s-1UNIX\s+1,
+ the shell has several additional capabilities.
+ .SS Special Commands
+ .PP
+ There are three additional commands built in to the shell. They are:
+ .RS
+ .TP
+ \fBatt\fP \*(OK command \*(CK
+ Switch the current ``universe'' to be ATT System V.
+ If a command is specified, that command will be run in the ``att''
+ universe, without affecting the shell's current universe.
+ The
+ .B \-t
+ option of
+ .B /bin/att
+ is not (yet) supported.
+ .TP
+ \fBucb\fP \*(OK command \*(CK
+ Switch the current ``universe'' to be University of California at
+ Berkeley 4.2BSD.
+ If a command is specified, that command will be run in the ``ucb''
+ universe, without affecting the shell's current universe.
+ The
+ .B \-t
+ option of
+ .B /bin/ucb
+ is not (yet) supported.
+ .TP
+ \fBuniverse\fP \*(OK \fB\-l\fP \*(CK
+ Print the current universe, either ``att'' or ``ucb''. The
+ .B \-l
+ option will print a longer, more explanative name for the current universe.
+ .RE
+ .PP
+ If the shell cannot determine the current universe when it starts up,
+ it will default to
+ .BR ucb .
+ .SS Shell Variables
+ .PP
+ There is an additional pre-defined shell parameter,
+ .BR \s-1UNIVERSE\s+1 .
+ The value of
+ .B \s-1UNIVERSE\s+1
+ .I always
+ tracks that of the current universe.  Using it is equivalent to a
+ \*`universe\` command substitution,
+ except that a new process will not be created.
+ This variable cannot be set by the user (it is \fBreadonly\fP),
+ and any inherited value from the environment will be ignored.
+ .SS Special Sequences for \s-1PS1\s+1
+ .PP
+ Finally, the sequence
+ .B %u
+ in the value of
+ .B \s-1PS1\s-1
+ will cause the shell to subsitute in the name of the current universe,
+ either ``att'' or ``ucb''.
+ .SH HISTORY EXAMPLES
+ Command history provides a powerful method for easily redoing previous
+ commands, or for quicly fixing typing mistakes.
+ Here are some annotated examples.  User input is in
+ .BR boldface .
+ .sp
+ .nf
+ # first, list some files
+ .RB "$ " lf
+ hello.c		echo.c
+ # now, make a typing mistake
+ .RB "$ " "cat hello"
+ hello: No such file or directory
+ # fix it.  The trailing ! ends the history substitution,
+ # in order to correctly concatenate it with the following .c
+ .RB "$ " "!!.c"
+ cat hello.c
+ main () { printf ("hello world\en"); }
+ # now look at echo.c instead
+ .RB "$ " "!^hello^echo"
+ cat echo.c
+ main () { printf ("echo: no arguments\en"); }
+ # do it again, just for fun
+ .RB "$ " "!"
+ cat echo.c
+ main () { printf ("echo: no arguments\en"); }
+ # now we'll rearrange some arguments
+ .RB "$ " "echo 1 2 3 4 5"
+ 1 2 3 4 5
+ # print last argument, first and second arguments, then change 4 to four
+ .RB "$ " "echo !\(ga$ !\(ga1-2 !\(ga4^4^four"
+ echo 5 1 2 four
+ 5 1 2 four
+ # do something with all the previous arguments at once
+ .RB "$ " "echo the previous arguments were !\(ga\-"
+ echo the previous arguments were 5 1 2 four
+ the previous arguments were 5 1 2 four
+ # now do some substitutions.  first get something to work with.
+ .RB "$ " "echo aa bb cc"
+ aa bb cc
+ # change the first 'a' to a 'b', and change all c's to d's
+ .RB "$ " "!^a^b^^c^d^g"
+ echo ba bb dd
+ ba bb dd
+ .fi
+ .PP
+ These few brief examples should provide a general feel for the
+ history mechanism.  The quickest way to learn it is to experiment
+ with it for a while, using the
+ .B echo
+ command, which can do very little damage.
+ While it looks cryptic when being typed, it is very general and
+ orthogonal, and quickly becomes natural.