commit bb75d87840ec0aa49c4ec0019e32c162054229a2
parent 0c8f724114bd5703a825cc8a9d7f9c7ae0acbfb3
Author: tjg <tjg>
Date: Tue, 20 Nov 2001 21:34:50 +0000
Documentation: tighten up various descriptions, and include some
more examples.
Release: rc-1.6c5.
Diffstat:
| M | rc.1 | | | 128 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------ |
1 file changed, 89 insertions(+), 39 deletions(-)
diff --git a/rc.1 b/rc.1
@@ -32,15 +32,15 @@
.\" for pointing out these problems.
.\"
.\" Note that sentences should end at the end of a line. nroff and
-.\" troff will supply the correct intersentence spacing, but only if
+.\" troff will supply the correct inter-sentence spacing, but only if
.\" the sentences end at the end of a line. Explicit spaces, if given,
-.\" are apparently honored and the normal intersentence spacing is
+.\" are apparently honored and the normal inter-sentence spacing is
.\" suppressed.
.\"
.\" DaviD W. Sanderson
.\"-------
.\" Dd distance to space vertically before a "display"
-.\" These are what n/troff use for interparagraph distance
+.\" These are what n/troff use for inter-paragraph distance
.\"-------
.if t .nr Dd .4v
.if n .nr Dd 1v
@@ -161,7 +161,7 @@
.if !"\\$4"" .Xf \\$2 \\$1 "\\$3\\f\\$1\\$4\\*(Xi" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
.if "\\$4"" \\$3\fR\s10
..
-.TH RC 1 "2001-10-31"
+.TH RC 1 "2001-11-20"
.SH NAME
rc \- shell
.SH SYNOPSIS
@@ -700,9 +700,7 @@ is omitted, then
will set
.I var
to each element of
-.Cr $*
-(excluding
-.Cr $0 ).
+.Cr $* .
For example:
.Ds
.Cr "for (i in \`{ls -F | grep '\e*$' | sed 's/\e*$//'}) { commands }"
@@ -876,7 +874,7 @@ Thus, the command
.PP
returns true if any of the files in the current directory have a
single-character name.
-(Note that if the
+If the
.Cr ~
command is given a list as its first
argument, then a successful match against any of the elements of that
@@ -888,7 +886,7 @@ For example:
.Cr "~ (foo goo zoo) z*"
.De
.PP
-is true.)
+is true.
.SH "LISTS AND VARIABLES"
The primary data structure in
.IR rc
@@ -926,18 +924,7 @@ produces the output
.SS "List Concatenation"
Two lists may be joined by the concatenation operator
.Rc ( ^ ).
-A single word is treated as a list of length one, so
-.Ds
-.Cr "echo foo^bar"
-.De
-.PP
-produces the output
-.Ds
-.Cr foobar
-.De
-.PP
-For lists of more than one element,
-concatenation works according to the following rules:
+Concatenation works according to the following rules:
if the two lists have the same number of elements,
then concatenation is pairwise:
.Ds
@@ -949,7 +936,7 @@ produces the output
.Cr "a\-1 b\-2 c\-3"
.De
.PP
-Otherwise, one of the lists must have a single element,
+Otherwise, at least one of the lists must have a single element,
and then the concatenation is distributive:
.Ds
.Cr "cc \-^(O g c) (malloc alloca)^.c"
@@ -959,6 +946,16 @@ has the effect of performing the command
.Ds
.Cr "cc \-O \-g \-c malloc.c alloca.c"
.De
+.PP
+A single word is a list of length one, so
+.Ds
+.Cr "echo foo^bar"
+.De
+.PP
+produces the output
+.Ds
+.Cr foobar
+.De
.SS "Free Carets"
.I rc
inserts carets (concatenation operators) for free in certain situations,
@@ -1215,6 +1212,8 @@ etc. are the same as
.Cr $*(1) ,
.Cr $*(2) ,
etc.
+.TP
+.Cr 0
The variable
.Cr $0
holds the value of
@@ -1231,18 +1230,49 @@ is also set to the name of the
file being interpreted for the duration of a
.Cr .
command.
+.Cr $0
+is not an element of
+.Cr $* ,
+and is never treated as one.
.TP
.Cr apid
The process ID of the last process started in the background.
.TP
.Cr apids " (read only)"
-The process IDs of any background processes which are outstanding
-or which have died and have not been waited for yet.
+A list whose elements are the process IDs of all background processes
+which are still alive, or which have died and have not been waited for
+yet.
.TP
.Cr bqstatus
The exit status of the
.I rc
-forked to execute the most recent backquote substitution.
+forked to execute the most recent backquote substitution. Note that, unlike
+.Cr $status ,
+.Cr $bqstatus
+is always a single element list (see
+.BR "EXIT STATUS"
+below). For example:
+.Ds
+.Cr "echo foo |grep bar; whatis status"
+.De
+.TP
+\&
+prints
+.Ds
+.Cr "status=(0 1)"
+.De
+.TP
+\&
+whereas
+.Ds
+.Cr "x=`{echo foo |grep bar}; whatis bqstatus"
+.De
+.TP
+\&
+prints
+.Ds
+.Cr "bqstatus=1"
+.De
.TP
.Cr cdpath
A list of directories to search for the target of a
@@ -1283,8 +1313,7 @@ does not append commands to any file.
.Cr home
The default directory for the builtin
.B cd
-command and is the directory
-in which
+command, and the directory in which
.I rc
looks to find its initialization file,
.Cr .rcrc ,
@@ -1365,7 +1394,7 @@ directly into a file for use as a shell script, without further editing
being necessary.
.TP
.Cr prompt " (function)"
-If this function is set, then it gets executed every time
+If this function is defined, then it gets executed every time
.I rc
is about to print
.Cr "$prompt(1)" .
@@ -1393,9 +1422,13 @@ to
.Cr "(0 0)" .
.TP
.Cr version " (read only)"
-This variable contains a string which identifies this
+The first element of this list variable is a string which identifies this
version of
.IR rc .
+The second element is a string which can be found by
+.IR ident
+and
+.IR "sccs what" .
.PP
The values of
.Cr "$path" ,
@@ -1570,6 +1603,22 @@ Executes the command ignoring any function definition of the
same name.
This command is present to allow functions with the
same names as builtins to use the underlying builtin or binary.
+For example:
+.Ds
+.Cr "fn ls { builtin ls -FC $* }"
+.De
+.TP
+\&
+is a reasonable way to pass a default set of arguments to
+.Cr ls (1).
+.Ds
+.Cr "fn ls { ls -FC $* }"
+.De
+.TP
+\&
+is a non-terminating recursion, which will cause
+.Cr rc
+to exhaust its stack space and (eventually) terminate if it is executed.
.TP
\fBcd \fR[\fIdirectory\fR]
Changes the current directory to
@@ -1673,7 +1722,7 @@ Returns from the current function, with status
.IR n ,
where
.IR n
-is a single value or a list of possible exit statuses.
+is a valid exit status, or a list of them.
Thus it is legal to have
.Ds
.Cr "return (sigpipe 1 2 3)"
@@ -1701,10 +1750,6 @@ elements down by
.IR n .
.I n
defaults to 1.
-(Note that
-.Cr $0
-is not affected by
-.BR shift .)
.TP
\fBumask \fR[\fImask\fR]
Sets the current umask (see
@@ -1714,15 +1759,16 @@ to the octal
If no argument is present, the current mask value is printed.
.TP
\fBwait \fR[\fIpid\fR]
-Waits for the specified
+Waits for process with the specified
.IR pid ,
which must have been started by
-.IR rc .
+.IR rc ,
+to exit.
If no
.I pid
is specified,
.I rc
-waits for all child processes to exit.
+waits for all its child processes to exit.
.TP
\fBwhatis \fR[\fB\-b\fR] \fR[\fB\-f\fR] \fR[\fB\-p\fR] \fR[\fB\-s\fR] \fR[\fB\-v\fR] [\fB\-\|\-\fR] [\fIname ...\fR]
Prints a definition of the named objects.
@@ -1825,7 +1871,7 @@ This function allows the separator to be an arbitrary string.
With this definition in place,
.Ds
.Cr "hops=(uunet mcvax ukc tlg)"
-.Cr lflat hops !
+.Cr "lflat hops !"
.De
.PP
prints (with no final newline)
@@ -1986,8 +2032,12 @@ doesn't use systems which lack
any more.
If anybody can reproduce this problem, please let the maintainer know.)
.PP
+The
.B echo
-is built in only for performance reasons, which is a bad idea.
+command does not need to be a builtin. It is one for reasons of
+performance and portability (of
+.I rc
+scripts).
.PP
There should be a way to avoid exporting a variable.
.PP
