update man page to pdksh v5.2.14

2 files changed, 278 insertions, 66 deletions

diff --git a/bin/ksh/ksh.1 b/bin/ksh/ksh.1
index dde9090dec9..8fb2f997879 100644
--- a/bin/ksh/ksh.1
+++ b/bin/ksh/ksh.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ksh.1,v 1.23 1999/07/05 19:50:53 aaron Exp $
+.\"	$OpenBSD: ksh.1,v 1.24 1999/07/14 15:18:49 aaron Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
 .\"     The Regents of the University of California.  All rights reserved.
@@ -674,6 +674,14 @@ Mostly the same as
 (see
 .Sx Functions
 below).
+.It Xo Ic time Op Fl p
+.Op Ar pipeline
+.Xc
+The
+.Ic time
+reserved word is described in the
+.Sx Command execution
+section.
 .It Ic (( Ar expression Ic ))
 The arithmetic expression
 .Ar expression
@@ -867,9 +875,9 @@ The first step the shell takes in executing a simple-command is to perform
 substitutions on the words of the command. There are three kinds of
 substitution: parameter, command, and arithmetic. Parameter substitutions,
 which are described in detail in the next section, take the form
-.Ic $name
+.Ic $ Ns Ar name
 or
-.Ic ${...} ;
+.Ic ${ Ns Ar ... Ns Ic \&} ;
 command substitutions take the form
 .Ic $( Ns Ar command Ns Ic )
 or
@@ -969,16 +977,25 @@ below, or a letter followed by zero or more letters or digits
 .Ql _
 counts as a letter
 .Pc .
+The later form can be treated as arrays by appending an array index of the
+form
+.Op Ar expr
+where
+.Ar expr
+is an arithmetic expression.
+Array indicies are currently limited to the range 0 through 1023, inclusive.
 Parameter substitutions take the form
-.Ic $ Ns Ar name
-or
+.Ic $ Ns Ar name ,
 .Ic ${ Ns Ar name Ns Ic \&} ,
+or
+.Sm off
+.Ic ${ Ar name Oo Ar expr Oc Ic \&} ,
+.Sm on
 where
 .Ar name
-is a parameter name. If substitution is performed on a parameter that is not
-set, a
-.Dv NULL
-string is substituted unless the
+is a parameter name.
+If substitution is performed on a parameter (or an array parameter element)
+that is not set, a null string is substituted unless the
 .Ic nounset
 option
 .Po
@@ -1331,10 +1348,10 @@ started.
 .It Ev KSH_VERSION
 The version of the shell and the date the version was created (read-only).
 See also the version commands in
-.Sx Emacs interactive input line editing
+.Sx Emacs editing mode
 and
-.Sx Vi interactive input line editing ,
-below.
+.Sx Vi editing mode
+sections, below.
 .It Ev LINENO
 The line number of the function or shell script that is currently being
 executed.
@@ -2204,7 +2221,21 @@ exit status. In
 .Tn POSIX
 mode, the exit status is 0 if no errors occur; in
 .Pf non- Tn POSIX
-mode,the exit status is that of the last foregrounded job.
+mode, the exit status is that of the last foregrounded job.
+.It
+.Ic eval
+exit status. If
+.Ic eval
+gets to see an empty command (i.e.,
+.Ic eval "`false`" ) ,
+its exit status in
+.Tn POSIX
+mode will be 0. In
+.Pf non- Tn POSIX
+mode, it will be the exit status of the last command substitution that was
+done in the processing of the arguments to
+.Ic eval
+(or 0 if there were no command substitutions).
 .It
 .Ic getopts .
 In
@@ -2479,7 +2510,7 @@ below for more information).
 .Oc
 .Xc
 Set or view the current emacs command editing key bindings/macros (see
-.Sx Emacs interactive input line editing
+.Sx Emacs editing mode
 below for a complete description).
 .It Ic break Op Ar level
 Exit the
@@ -3114,16 +3145,18 @@ Background jobs are run with lower priority.
 Enable brace expansion (a.k.a., alternation).
 .It Ic emacs
 Enable BRL emacs-like command-line editing (interactive shells only); see
-.Sx Emacs interactive input line editing
-below.
+.Sx Emacs editing mode.
 .It Ic gmacs
 Enable gmacs-like command-line editing (interactive shells only). Currently
 identical to emacs editing except that transpose (^T) acts slightly
 differently.
 .It Ic ignoreeof
-The shell will not exit when end-of-file is read;
+The shell will not (easily) exit when end-of-file is read;
 .Ic exit
 must be used.
+To avoid infinite loops, the shell will exit if
+.Dv EOF
+is read 13 times in a row.
 .It Ic nohup
 Do not kill running jobs with a
 .Dv HUP
@@ -3325,12 +3358,22 @@ exists).
 first
 .Ar file
 is newer than second
-.Ar file .
+.Ar file
+or first
+.Ar file
+exists and the second
+.Ar file
+does not.
 .It Ar file Fl ot Ar file
 first
 .Ar file
 is older than second
-.Ar file .
+.Ar file
+or second
+.Ar file
+exists and the first
+.Ar file
+does not.
 .It Ar file Fl ef Ar file
 first
 .Ar file
@@ -3440,6 +3483,41 @@ or
 Use tests like
 .Ic if \&[ \&"X$foo\&" = Xbar \&]
 instead.
+.It Xo Ic time Op Fl p
+.Op Ar pipeline
+.Xc
+If a
+.Ar pipeline
+is given, the times used to execute the pipeline are reported. If no pipeline
+is given, then the user and system time used by the shell itself, and all the
+commands it has run since it was started, are reported.
+The times reported are the real time (elapsed time from start to finish),
+the user CPU time (time spent running in user mode), and the system CPU time
+(time spent running in kernel mode).
+Times are reported to standard error; the format of the output is:
+.Pp
+.Dl 0.00s real    0.00s user    0.00s system
+.Pp
+unless the
+.Fl p
+option is given (only possible if
+.Ar pipeline
+is a simple command), in which case the output is slightly longer:
+.Pp
+.Dl real   0.00
+.Dl user   0.00
+.Dl sys    0.00
+.Pp
+(the number of digits after the decimal may vary from system to system). Note
+that simple redirections of standard error do not effect the output of the time
+command:
+.Pp
+.Dl time sleep 1 2> afile
+.Dl { time sleep 1; } 2> afile
+.Pp
+Times for the first command do not go to
+.Dq afile ,
+but those of the second command do.
 .It Ic times
 Print the accumulated user and system times used by the shell and by processes
 which have exited that the shell started.
@@ -3486,8 +3564,12 @@ With no arguments,
 .Ic trap
 lists, as a series of
 .Ic trap
-commands, the current start of the traps that have been set since the shell
+commands, the current state of the traps that have been set since the shell
 started.
+Note that the ouput of
+.Ic trap
+can not be usefully piped to another process (an artifact of the fact that
+traps are cleared when subprocesses are created).
 .Pp
 The original Korn shell's
 .Dv DEBUG
@@ -3936,7 +4018,39 @@ a login shell, the shell warns the user and does not exit. If another attempt
 is immediately made to exit the shell, the running jobs are sent a
 .Dv SIGHUP
 signal and the shell exits.
-.Ss Emacs interactive input line editing
+.Ss Interactive input line editing
+The shell supports three modes of reading command lines from a tty in an
+interactive session, which is controlled by the
+.Ic emacs ,
+.Ic gmacs ,
+and
+.Ic vi
+options (at most one of these can be set an once).
+If none of these options are enabled, the shell simply reads lines using the
+normal tty driver.
+If the
+.Ic emacs
+or
+.Ic gmacs
+option is set, the shell allows emacs-like editing of the command; similarly,
+if the
+.Ic vi
+option is set, the shell allows vi-like editing of the command.
+These modes are described in detail in the following sections.
+.Pp
+In these editing modes, if a line is longer than the screen width (see
+.Ev COLUMNS
+parameter),
+a
+.Ql > ,
+.Ql + ,
+or
+.Ql <
+character is displayed in the last column indicating that there are more
+characters after, before and after, or before the current position,
+respectively.
+The line is scrolled horizontally as necessary.
+.Ss Emacs editing mode
 When the
 .Ic emacs
 option is set, interactive input line editing is enabled. Warning: This mode is
@@ -4234,7 +4348,7 @@ Immediately after a
 .Ic yank ,
 replaces the inserted text string with the next previously killed text string.
 .El
-.Ss Vi interactive input line editing
+.Ss Vi editing mode
 The vi command-line editor in ksh has basically the same commands as the vi
 editor (see
 .Xr vi 1 ) ,
@@ -4310,17 +4424,6 @@ above), enabled with
 .Ic set Fl o Ic vi-tabcomplete .
 .El
 .Pp
-If a line is longer than the screen width (see
-.Dv COLUMNS
-parameter), a
-.Ql > ,
-.Ql +
-or
-.Ql <
-character is displayed in the last column indicating that there are more
-characters after, before and after, or before the current position,
-respectively. The line is scrolled horizontally as necessary.
-.Pp
 In command mode, each character is interpreted as a command. Characters that
 don't correspond to commands, are illegal combinations of commands, or are
 commands that can't be carried out all cause beeps. In the following command
@@ -4742,6 +4845,9 @@ echo hi | read a; echo $a\ \ \ # Does not print hi
 .Ed
 .Pp
 I'm aware of this and there is no need to report it.
+.Sh VERSION
+This page documents version @(#)PD KSH v5.2.14 99/07/13.2 of the public
+domain Korn shell.
 .Sh AUTHORS
 This shell is based on the public domain 7th edition Bourne shell clone by
 Charles Forsyth and parts of the BRL shell by Doug A. Gwyn, Doug Kingston,
diff --git a/bin/ksh/ksh.1tbl b/bin/ksh/ksh.1tbl
index a2b546607cd..a5cb70425e4 100644
--- a/bin/ksh/ksh.1tbl
+++ b/bin/ksh/ksh.1tbl
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ksh.1tbl,v 1.23 1999/07/05 19:50:53 aaron Exp $
+.\"	$OpenBSD: ksh.1tbl,v 1.24 1999/07/14 15:18:49 aaron Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
 .\"     The Regents of the University of California.  All rights reserved.
@@ -674,6 +674,14 @@ Mostly the same as
 (see
 .Sx Functions
 below).
+.It Xo Ic time Op Fl p
+.Op Ar pipeline
+.Xc
+The
+.Ic time
+reserved word is described in the
+.Sx Command execution
+section.
 .It Ic (( Ar expression Ic ))
 The arithmetic expression
 .Ar expression
@@ -867,9 +875,9 @@ The first step the shell takes in executing a simple-command is to perform
 substitutions on the words of the command. There are three kinds of
 substitution: parameter, command, and arithmetic. Parameter substitutions,
 which are described in detail in the next section, take the form
-.Ic $name
+.Ic $ Ns Ar name
 or
-.Ic ${...} ;
+.Ic ${ Ns Ar ... Ns Ic \&} ;
 command substitutions take the form
 .Ic $( Ns Ar command Ns Ic )
 or
@@ -969,16 +977,25 @@ below, or a letter followed by zero or more letters or digits
 .Ql _
 counts as a letter
 .Pc .
+The later form can be treated as arrays by appending an array index of the
+form
+.Op Ar expr
+where
+.Ar expr
+is an arithmetic expression.
+Array indicies are currently limited to the range 0 through 1023, inclusive.
 Parameter substitutions take the form
-.Ic $ Ns Ar name
-or
+.Ic $ Ns Ar name ,
 .Ic ${ Ns Ar name Ns Ic \&} ,
+or
+.Sm off
+.Ic ${ Ar name Oo Ar expr Oc Ic \&} ,
+.Sm on
 where
 .Ar name
-is a parameter name. If substitution is performed on a parameter that is not
-set, a
-.Dv NULL
-string is substituted unless the
+is a parameter name.
+If substitution is performed on a parameter (or an array parameter element)
+that is not set, a null string is substituted unless the
 .Ic nounset
 option
 .Po
@@ -1331,10 +1348,10 @@ started.
 .It Ev KSH_VERSION
 The version of the shell and the date the version was created (read-only).
 See also the version commands in
-.Sx Emacs interactive input line editing
+.Sx Emacs editing mode
 and
-.Sx Vi interactive input line editing ,
-below.
+.Sx Vi editing mode
+sections, below.
 .It Ev LINENO
 The line number of the function or shell script that is currently being
 executed.
@@ -2204,7 +2221,21 @@ exit status. In
 .Tn POSIX
 mode, the exit status is 0 if no errors occur; in
 .Pf non- Tn POSIX
-mode,the exit status is that of the last foregrounded job.
+mode, the exit status is that of the last foregrounded job.
+.It
+.Ic eval
+exit status. If
+.Ic eval
+gets to see an empty command (i.e.,
+.Ic eval "`false`" ) ,
+its exit status in
+.Tn POSIX
+mode will be 0. In
+.Pf non- Tn POSIX
+mode, it will be the exit status of the last command substitution that was
+done in the processing of the arguments to
+.Ic eval
+(or 0 if there were no command substitutions).
 .It
 .Ic getopts .
 In
@@ -2479,7 +2510,7 @@ below for more information).
 .Oc
 .Xc
 Set or view the current emacs command editing key bindings/macros (see
-.Sx Emacs interactive input line editing
+.Sx Emacs editing mode
 below for a complete description).
 .It Ic break Op Ar level
 Exit the
@@ -3114,16 +3145,18 @@ Background jobs are run with lower priority.
 Enable brace expansion (a.k.a., alternation).
 .It Ic emacs
 Enable BRL emacs-like command-line editing (interactive shells only); see
-.Sx Emacs interactive input line editing
-below.
+.Sx Emacs editing mode.
 .It Ic gmacs
 Enable gmacs-like command-line editing (interactive shells only). Currently
 identical to emacs editing except that transpose (^T) acts slightly
 differently.
 .It Ic ignoreeof
-The shell will not exit when end-of-file is read;
+The shell will not (easily) exit when end-of-file is read;
 .Ic exit
 must be used.
+To avoid infinite loops, the shell will exit if
+.Dv EOF
+is read 13 times in a row.
 .It Ic nohup
 Do not kill running jobs with a
 .Dv HUP
@@ -3325,12 +3358,22 @@ exists).
 first
 .Ar file
 is newer than second
-.Ar file .
+.Ar file
+or first
+.Ar file
+exists and the second
+.Ar file
+does not.
 .It Ar file Fl ot Ar file
 first
 .Ar file
 is older than second
-.Ar file .
+.Ar file
+or second
+.Ar file
+exists and the first
+.Ar file
+does not.
 .It Ar file Fl ef Ar file
 first
 .Ar file
@@ -3440,6 +3483,41 @@ or
 Use tests like
 .Ic if \&[ \&"X$foo\&" = Xbar \&]
 instead.
+.It Xo Ic time Op Fl p
+.Op Ar pipeline
+.Xc
+If a
+.Ar pipeline
+is given, the times used to execute the pipeline are reported. If no pipeline
+is given, then the user and system time used by the shell itself, and all the
+commands it has run since it was started, are reported.
+The times reported are the real time (elapsed time from start to finish),
+the user CPU time (time spent running in user mode), and the system CPU time
+(time spent running in kernel mode).
+Times are reported to standard error; the format of the output is:
+.Pp
+.Dl 0.00s real    0.00s user    0.00s system
+.Pp
+unless the
+.Fl p
+option is given (only possible if
+.Ar pipeline
+is a simple command), in which case the output is slightly longer:
+.Pp
+.Dl real   0.00
+.Dl user   0.00
+.Dl sys    0.00
+.Pp
+(the number of digits after the decimal may vary from system to system). Note
+that simple redirections of standard error do not effect the output of the time
+command:
+.Pp
+.Dl time sleep 1 2> afile
+.Dl { time sleep 1; } 2> afile
+.Pp
+Times for the first command do not go to
+.Dq afile ,
+but those of the second command do.
 .It Ic times
 Print the accumulated user and system times used by the shell and by processes
 which have exited that the shell started.
@@ -3486,8 +3564,12 @@ With no arguments,
 .Ic trap
 lists, as a series of
 .Ic trap
-commands, the current start of the traps that have been set since the shell
+commands, the current state of the traps that have been set since the shell
 started.
+Note that the ouput of
+.Ic trap
+can not be usefully piped to another process (an artifact of the fact that
+traps are cleared when subprocesses are created).
 .Pp
 The original Korn shell's
 .Dv DEBUG
@@ -3936,7 +4018,39 @@ a login shell, the shell warns the user and does not exit. If another attempt
 is immediately made to exit the shell, the running jobs are sent a
 .Dv SIGHUP
 signal and the shell exits.
-.Ss Emacs interactive input line editing
+.Ss Interactive input line editing
+The shell supports three modes of reading command lines from a tty in an
+interactive session, which is controlled by the
+.Ic emacs ,
+.Ic gmacs ,
+and
+.Ic vi
+options (at most one of these can be set an once).
+If none of these options are enabled, the shell simply reads lines using the
+normal tty driver.
+If the
+.Ic emacs
+or
+.Ic gmacs
+option is set, the shell allows emacs-like editing of the command; similarly,
+if the
+.Ic vi
+option is set, the shell allows vi-like editing of the command.
+These modes are described in detail in the following sections.
+.Pp
+In these editing modes, if a line is longer than the screen width (see
+.Ev COLUMNS
+parameter),
+a
+.Ql > ,
+.Ql + ,
+or
+.Ql <
+character is displayed in the last column indicating that there are more
+characters after, before and after, or before the current position,
+respectively.
+The line is scrolled horizontally as necessary.
+.Ss Emacs editing mode
 When the
 .Ic emacs
 option is set, interactive input line editing is enabled. Warning: This mode is
@@ -4234,7 +4348,7 @@ Immediately after a
 .Ic yank ,
 replaces the inserted text string with the next previously killed text string.
 .El
-.Ss Vi interactive input line editing
+.Ss Vi editing mode
 The vi command-line editor in ksh has basically the same commands as the vi
 editor (see
 .Xr vi 1 ) ,
@@ -4310,17 +4424,6 @@ above), enabled with
 .Ic set Fl o Ic vi-tabcomplete .
 .El
 .Pp
-If a line is longer than the screen width (see
-.Dv COLUMNS
-parameter), a
-.Ql > ,
-.Ql +
-or
-.Ql <
-character is displayed in the last column indicating that there are more
-characters after, before and after, or before the current position,
-respectively. The line is scrolled horizontally as necessary.
-.Pp
 In command mode, each character is interpreted as a command. Characters that
 don't correspond to commands, are illegal combinations of commands, or are
 commands that can't be carried out all cause beeps. In the following command
@@ -4742,6 +4845,9 @@ echo hi | read a; echo $a\ \ \ # Does not print hi
 .Ed
 .Pp
 I'm aware of this and there is no need to report it.
+.Sh VERSION
+This page documents version @(#)PD KSH v5.2.14 99/07/13.2 of the public
+domain Korn shell.
 .Sh AUTHORS
 This shell is based on the public domain 7th edition Bourne shell clone by
 Charles Forsyth and parts of the BRL shell by Doug A. Gwyn, Doug Kingston,