rc

[fork] interactive rc shell
Log | Files | Refs | README | LICENSE

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:
Mrc.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