1RC(1)                       General Commands Manual                      RC(1)
2
3
4

NAME

6       rc - shell
7

SYNOPSIS

9       rc [-deiIlnopsvx] [-c command] [arguments]
10

DESCRIPTION

12       rc  is a command interpreter and programming language similar to sh(1).
13       It is based on the AT&T Plan 9 shell  of  the  same  name.   The  shell
14       offers  a C-like syntax (much more so than the C shell), and a powerful
15       mechanism for manipulating variables.  It is reasonably small and  rea‐
16       sonably fast, especially when compared to contemporary shells.  Its use
17       is intended to be interactive, but the language lends  itself  well  to
18       scripts.
19

OPTIONS

21       -c     If  -c  is  present,  commands are executed from the immediately
22              following argument.  Any further arguments to rc are  placed  in
23              $*.  Thus:
24
25                   rc -c 'echo $*' 1 2 3
26
27              prints out
28
29                   1 2 3
30
31       -d     This  flag  causes rc not to ignore SIGQUIT or SIGTERM.  Thus rc
32              can be made to dump core if sent SIGQUIT.   This  flag  is  only
33              useful for debugging rc.
34
35       -e     If  the -e flag is present, then rc will exit if the exit status
36              of a command is false (nonzero).  rc will not exit, however,  if
37              a conditional fails, e.g., an if() command.
38
39       -i     If the -i flag is present or if the input to rc is from a termi‐
40              nal (as determined by isatty(3)) then rc will be in  interactive
41              mode.   That  is,  a  prompt  (from  $prompt(1)) will be printed
42              before an input line is taken, and rc will ignore SIGINT.
43
44       -I     If the -I flag is present, or if the input to rc is not  from  a
45              terminal,  then  rc will not be in interactive mode.  No prompts
46              will be printed, and SIGINT will cause rc to exit.
47
48       -l     If the -l flag is present, or if rc's argv[0][0] is a dash  (-),
49              then rc will behave as a login shell.  That is, it will run com‐
50              mands from $home/.rcrc, if this file exists, before reading  any
51              other input.
52
53       -n     This  flag  causes rc to read its input and parse it, but not to
54              execute any commands.  This is useful  for  syntax  checking  on
55              scripts.  If used in combination with the -x flag, rc will print
56              each command as it is parsed in a form similar to the  one  used
57              for exporting functions into the environment.
58
59       -o     This  flag  prevents  the  usual  practice  of  trying  to  open
60              /dev/null on file descriptors 0, 1,  and  2,  if  any  of  those
61              descriptors are inherited closed.
62
63       -p     This flag prevents rc from initializing shell functions from the
64              environment.  This allows rc to run in a protected mode, whereby
65              it  becomes  more  difficult for an rc script to be subverted by
66              placing false commands in the environment.  (Note that the pres‐
67              ence of this flag does not mean that it is safe to run setuid rc
68              scripts; the usual caveats about the setuid bit still apply.)
69
70       -s     This flag causes rc to read from standard input.  Any  arguments
71              are placed in $*.
72
73       -v     This flag causes rc to echo its input to standard error as it is
74              read.
75
76       -x     This flag causes rc to print every  command  on  standard  error
77              before  it  is  executed.   It  can  be  useful for debugging rc
78              scripts.
79

COMMANDS

81       A simple command is a sequence  of  words,  separated  by  white  space
82       (space  and tab) characters that ends with a newline, semicolon (;), or
83       ampersand (&).  The first word of a command is the name  of  that  com‐
84       mand.   If the name begins with /, ./, or ../, then the name is used as
85       an absolute path name referring to an executable file.  Otherwise,  the
86       name of the command is looked up in a table of shell functions, builtin
87       commands, or as a file in the directories named by $path.
88
89   Background Tasks
90       A command ending with & is run in the background; that  is,  the  shell
91       returns  immediately  rather  than waiting for the command to complete.
92       Background commands have /dev/null connected to  their  standard  input
93       unless an explicit redirection for standard input is used.
94
95   Subshells
96       A command prefixed with an at-sign (@) is executed in a subshell.  This
97       insulates the parent shell from the effects of  state  changing  opera‐
98       tions such as a cd or a variable assignment.  For example:
99
100            @ {cd ..; make}
101
102       will  run  make(1)  in  the parent directory (..), but leaves the shell
103       running in the current directory.
104
105   Line continuation
106       A long logical line may be continued over  several  physical  lines  by
107       terminating  each  line  (except  the  last) with a backslash (\).  The
108       backslash-newline sequence is treated as a space.  A backslash  is  not
109       otherwise special to rc.  (In addition, inside quotes a backslash loses
110       its special meaning even when it is followed by a newline.)
111
112   Quoting
113       rc interprets several characters specially; special characters automat‐
114       ically terminate words.  The following characters are special:
115
116            # ; & | ^ $ = ` ' { } ( ) < >
117
118       The  single quote (') prevents special treatment of any character other
119       than itself.  All characters, including control  characters,  newlines,
120       and backslashes between two quote characters are treated as an uninter‐
121       preted string.  A quote character itself may be quoted by  placing  two
122       quotes  in a row.  The minimal sequence needed to enter the quote char‐
123       acter is ''''.  The empty string is represented by ''.  Thus:
124
125            echo 'What''s the plan, Stan?'
126
127       prints out
128
129            What's the plan, Stan?
130
131       The number sign (#) begins a comment in rc.  All characters up  to  but
132       not  including  the next newline are ignored.  Note that backslash con‐
133       tinuation does not work  inside  a  comment,  i.e.,  the  backslash  is
134       ignored along with everything else.
135
136   Grouping
137       Zero  or  more commands may be grouped within braces (``{'' and ``}''),
138       and are then treated as one command.  Braces do  not  otherwise  define
139       scope; they are used only for command grouping.  In particular, be wary
140       of the command:
141
142            for (i) {
143                command
144            } | command
145
146       Since pipe binds tighter than for, this command does not  perform  what
147       the  user  expects  it to.  Instead, enclose the whole for statement in
148       braces:
149
150            {for (i) command} | command
151
152       Fortunately, rc's grammar is simple enough that a (confident) user  can
153       understand  it  by examining the skeletal yacc(1) grammar at the end of
154       this man page (see the section entitled GRAMMAR).
155
156   Input and output
157       The standard output may be redirected to a file with
158
159            command > file
160
161       and the standard input may be taken from a file with
162
163            command < file
164
165       Redirections can appear anywhere in the line: the  word  following  the
166       redirection  symbol  is  the filename and must be quoted if it contains
167       spaces or other special characters.  These are all equivalent.
168
169            echo 1 2 3 > foo
170            > foo echo 1 2 3
171            echo 1 2 > foo 3
172
173       File descriptors other than 0 and 1 may be specified also.   For  exam‐
174       ple, to redirect standard error to a file, use:
175
176            command >[2] file
177
178       In  order to duplicate a file descriptor, use >[n=m].  Thus to redirect
179       both standard output and standard error to the same file, use
180
181            command > file >[2=1]
182
183       As in sh, redirections are processed from left  to  right.   Thus  this
184       sequence
185
186            command >[2=1] > file
187
188       is  usually  a mistake.  It first duplicates standard error to standard
189       output; then redirects standard output  to  a  file,  leaving  standard
190       error wherever standard output originally was.
191
192       To  close  a file descriptor that may be open, use >[n=].  For example,
193       to close file descriptor 7:
194
195            command >[7=]
196
197       Note that no spaces may appear in these constructs:
198
199            command > [2] file
200
201       would send the output of the command to a  file  named  [2],  with  the
202       intended filename appearing in the command's argument list.
203
204       In  order  to  place  the  output of a command at the end of an already
205       existing file, use:
206
207            command >> file
208
209       If the file does not exist, then it is created.
210
211       ``Here documents'' are supported as in sh with the use of
212
213            command << 'eof-marker'
214
215       Subsequent lines form the standard input of the command,  till  a  line
216       containing just the marker, in this case eof-marker, is encountered.
217
218       If  the end-of-file marker is enclosed in quotes, then no variable sub‐
219       stitution occurs inside the here document.  Otherwise,  every  variable
220       is  substituted  by  its  space-separated-list  value  (see Flat Lists,
221       below), and if a ^ character follows a variable name,  it  is  deleted.
222       This allows the unambiguous use of variables adjacent to text, as in
223
224            $variable^follow
225
226       To  include a literal $ in a here document when an unquoted end-of-file
227       marker is being used, enter it as $$.
228
229       Additionally, rc supports ``here strings'', which are like  here  docu‐
230       ments, except that input is taken directly from a string on the command
231       line.  Their use is illustrated here:
232
233            cat <<< 'this is a here string' | wc
234
235       (This feature enables rc to export functions using here documents  into
236       the  environment; the author does not expect users to find this feature
237       useful.)
238
239   Pipes
240       Two or more commands may be combined in a pipeline by placing the  ver‐
241       tical bar (|) between them.  The standard output (file descriptor 1) of
242       the command on the left is tied to the standard input (file  descriptor
243       0)  of  the  command  on the right.  The notation |[n=m] indicates that
244       file descriptor n of the left process is connected to file descriptor m
245       of  the right process.  |[n] is a shorthand for |[n=0].  As an example,
246       to pipe the standard error of a command to wc(1), use:
247
248            command |[2] wc
249
250       As with file redirections, no spaces may occur in the construct  speci‐
251       fying numbered file descriptors.
252
253       The  exit  status of a pipeline is considered true if and only if every
254       command in the pipeline exits true.
255
256   Commands as Arguments
257       Some commands, like cmp(1) or diff(1), take their arguments on the com‐
258       mand line, and do not read input from standard input.  It is convenient
259       sometimes to build nonlinear pipelines so that a command like  cmp  can
260       read the output of two other commands at once.  rc does it like this:
261
262            cmp <{command} <{command}
263
264       compares  the  output  of the two commands in braces.  Note: since this
265       form of redirection is implemented with some kind of  pipe,  and  since
266       one  cannot  lseek(2)  on a pipe, commands that use lseek(2) will hang.
267       For example, some versions of diff(1) use lseek(2) on their inputs.
268
269       Data can be sent down a pipe to several commands using tee(1)  and  the
270       output version of this notation:
271
272            echo hi there | tee >{sed 's/^/p1 /'} >{sed 's/^/p2 /'}
273

CONTROL STRUCTURES

275       The following may be used for control flow in rc:
276
277   If-Else Statements
278       if (test) {
279           cmd
280       } else cmd
281              The  test  is  executed,  and  if its return status is zero, the
282              first command is executed, otherwise the second is.  Braces  are
283              not  mandatory  around the commands.  However, an else statement
284              is valid only if it follows a  close-brace  on  the  same  line.
285              Otherwise, the if is taken to be a simple-if:
286
287                   if (test)
288                       command
289
290   While and For Loops
291       while (test) cmd
292              rc  executes  the  test  and performs the command as long as the
293              test is true.
294
295       for (var in list) cmd
296              rc sets var to each element of list (which may contain variables
297              and  backquote  substitutions)  and runs cmd.  If ``in list'' is
298              omitted, then rc will set var to each element of $*.  For  exam‐
299              ple:
300
301                   for (i in `{ls -F | grep '\*$' | sed 's/\*$//'}) { commands }
302
303              will  set  $i  to the name of each file in the current directory
304              that is executable.
305
306   Switch
307       switch (list) { case ... }
308              rc looks inside the braces after a switch for statements  begin‐
309              ning  with the word case.  If any of the patterns following case
310              match the list supplied to switch, then the  commands  up  until
311              the  next  case statement are executed.  The metacharacters *, [
312              or ?  should not be quoted; matching is performed  only  against
313              the strings in list, not against file names.  (Matching for case
314              statements is the same as for the ~ command.)
315
316   Logical Operators
317       There are a number of operators in rc which depend on the  exit  status
318       of a command.
319
320            command && command
321
322       executes  the first command and then executes the second command if and
323       only if the first command exits with a zero exit  status  (``true''  in
324       Unix).
325
326            command || command
327
328       executes  the first command and then executes the second command if and
329       only if the first command exits with a nonzero exit  status  (``false''
330       in Unix).
331
332            ! command
333
334       negates the exit status of a command.
335

PATTERN MATCHING

337       There  are  two  forms  of  pattern matching in rc.  One is traditional
338       shell globbing.  This occurs in matching for  file  names  in  argument
339       lists:
340
341            command argument argument ...
342
343       When  the  characters  *,  [  or ?  occur in an argument or command, rc
344       looks at the argument as a pattern for matching against  files.   (Con‐
345       trary  to  the behavior other shells exhibit, rc will only perform pat‐
346       tern matching if a metacharacter occurs unquoted and literally  in  the
347       input.  Thus,
348
349            foo='*'
350            echo $foo
351
352       will  always echo just a star.  In order for non-literal metacharacters
353       to be expanded, an eval statement must be used in order to  rescan  the
354       input.)   Pattern matching occurs according to the following rules: a *
355       matches any number (including zero) of characters.  A  ?   matches  any
356       single  character,  and a [ followed by a number of characters followed
357       by a ] matches a single character in that class.  The rules for charac‐
358       ter  class matching are the same as those for ed(1), with the exception
359       that character class negation is achieved with the tilde (~),  not  the
360       caret (^), since the caret already means something else in rc.
361
362       rc also matches patterns against strings with the ~ command:
363
364            ~ subject pattern pattern ...
365
366       ~  sets  $status  to zero if and only if a supplied pattern matches any
367       single element of the subject list.  Thus
368
369            ~ foo f*
370
371       sets status to zero, while
372
373            ~ (bar baz) f*
374
375       sets status to one.  The null list is matched by the null list, so
376
377            ~ $foo ()
378
379       checks to see whether $foo is empty or not.  This may also be  achieved
380       by the test
381
382            ~ $#foo 0
383
384       Note  that  inside  a ~ command rc does not match patterns against file
385       names, so it is not necessary to quote the characters *, [ and ?.  How‐
386       ever,  rc  does  expand  the  subject  against filenames if it contains
387       metacharacters.  Thus, the command
388
389            ~ * ?
390
391       returns true if any of the files in the current directory have  a  sin‐
392       gle-character  name.   If  the  ~  command is given a list as its first
393       argument, then a successful match against any of the elements  of  that
394       list will cause ~ to return true.  For example:
395
396            ~ (foo goo zoo) z*
397
398       is true.
399

LISTS AND VARIABLES

401       The  primary  data  structure in rc is the list, which is a sequence of
402       words.  Parentheses are used to group lists.  The empty list is  repre‐
403       sented  by  ().   Lists  have  no hierarchical structure; a list inside
404       another list is expanded so the outer list contains all the elements of
405       the inner list.  Thus, the following are all equivalent
406
407            one two three
408
409            (one two three)
410
411            ((one) () ((two three)))
412
413       Note that the null string, '', and the null list, (), are two very dif‐
414       ferent things.  Assigning the null string to  a  variable  is  a  valid
415       operation, but it does not remove its definition.
416
417            null = '' empty = () echo $#null $#empty
418
419       produces the output
420
421            1 0
422
423   List Concatenation
424       Two  lists may be joined by the concatenation operator (^).  Concatena‐
425       tion works according to the following rules: if the two lists have  the
426       same number of elements, then concatenation is pairwise:
427
428            echo (a- b- c-)^(1 2 3)
429
430       produces the output
431
432            a-1 b-2 c-3
433
434       Otherwise,  at  least  one of the lists must have a single element, and
435       then the concatenation is distributive:
436
437            cc -^(O g c) (malloc alloca)^.c
438
439       has the effect of performing the command
440
441            cc -O -g -c malloc.c alloca.c
442
443       A single word is a list of length one, so
444
445            echo foo^bar
446
447       produces the output
448
449            foobar
450
451   Free Carets
452       rc inserts carets (concatenation operators) for free in certain  situa‐
453       tions, in order to save some typing on the user's behalf.  For example,
454       the above example could also be typed in as:
455
456            opts=(O g c) files=(malloc alloca) cc -$opts $files.c
457
458       rc takes care to insert a free-caret between the ``-''  and  $opts,  as
459       well as between $files and .c.  The rule for free carets is as follows:
460       if a word or keyword is immediately followed by another word,  keyword,
461       dollar-sign or backquote, then rc inserts a caret between them.
462
463   Variables
464       A list may be assigned to a variable, using the notation:
465
466            var = list
467
468       The  special variable * may also be assigned to using this notation; rc
469       has no set builtin.
470
471       Any non-empty sequence of characters, except a sequence including  only
472       digits,  may be used as a variable name.  Any character except = may be
473       used, but special characters must be quoted.   All  user-defined  vari‐
474       ables are exported into the environment.
475
476       The value of a variable is referenced with the dollar ($) operator:
477
478            $var
479
480       Any variable which has not been assigned a value returns the null list,
481       (), when referenced.  Multiple references are allowed:
482
483            a = foo
484            b = a
485            echo $ $ b
486
487       prints
488
489            foo
490
491       A variable's definition may also be removed by assigning the null  list
492       to a variable:
493
494            var=()
495
496       For  ``free  careting'' to work correctly, rc must make certain assump‐
497       tions about what characters may appear in a variable name.  rc  assumes
498       that  a  variable name consists only of alphanumeric characters, under‐
499       score (_) and star (*).  To reference a variable with other  characters
500       in its name, quote the variable name.  Thus:
501
502            echo $'we$Ird:Variab!le'
503
504   Local Variables
505       Any  number  of variable assignments may be made local to a single com‐
506       mand by typing:
507
508            a=foo b=bar ... command
509
510       The command may be a compound command, so for example:
511
512            path=. ifs=() {
513                ...
514            }
515
516       sets path to .  and removes ifs for the duration of one  long  compound
517       command.
518
519   Variable Subscripts
520       Variables may be subscripted with the notation
521
522            $var(n)
523
524       where n is a list of integers (origin 1).  The opening parenthesis must
525       immediately follow the variable name.  The list of subscripts need  not
526       be in order or even unique.  Thus,
527
528            a=(one two three)
529            echo $a(3 3 3)
530
531       prints
532
533            three three three
534
535       If  n  references  a nonexistent element, then $var(n) returns the null
536       list.  The notation $n, where n is  an  integer,  is  a  shorthand  for
537       $*(n).  Thus, rc's arguments may be referred to as $1, $2, and so on.
538
539       Note  also that the list of subscripts may be given by any of rc's list
540       operations:
541
542            $var(`{awk 'BEGIN{for(i=1;i<=10;i++)print i;exit; }'})
543
544       returns the first 10 elements of $var.
545
546       To count the number of elements in a variable, use
547
548            $#var
549
550       This returns a single-element list, with  the  number  of  elements  in
551       $var.
552
553   Flat Lists
554       In  order  to  create  a single-element list from a multi-element list,
555       with the components space-separated, use the dollar-caret  ($^)  opera‐
556       tor:
557
558            $^var
559
560       This  is  useful  when  the  normal list concatenation rules need to be
561       bypassed.  For example, to append a single period at the end of  $path,
562       use:
563
564            echo $^path.
565
566       For compability with the Plan 9 rc,
567
568            $"var
569
570       is accepted as a synonym for dollar-caret.
571
572   Backquote Substitution
573       A  list  may  be formed from the output of a command by using backquote
574       substitution:
575
576            `{ command }
577
578       returns a list formed from  the  standard  output  of  the  command  in
579       braces.   $ifs  is  used  to  split  the output into list elements.  By
580       default, $ifs has the value space-tab-newline.  The braces may be omit‐
581       ted  if  the command is a single word.  Thus `ls may be used instead of
582       `{ls}.  This last feature is useful when defining functions that expand
583       to useful argument lists.  A frequent use is:
584
585            fn src { echo *.[chy] }
586
587       followed by
588
589            wc `src
590
591       (This  will print out a word-count of all C source files in the current
592       directory.)
593
594       In order to override the value of $ifs for a single backquote substitu‐
595       tion, use:
596
597            `` (ifs-list) { command }
598
599       $ifs will be temporarily ignored and the command's output will be split
600       as specified by the list following the double backquote.  For example:
601
602            `` ($nl :) {cat /etc/passwd}
603
604       splits up /etc/passwd into fields, assuming that $nl contains a newline
605       as its value.
606

SPECIAL VARIABLES

608       Several  variables  are  known to rc and are treated specially.  In the
609       following list, ``default'' indicates that  rc  gives  the  variable  a
610       default  value on startup; ``no-export'' indicates that the variable is
611       never exported; and ``read-only'' indicates that an attempt to set  the
612       variable will silently have no effect.
613
614       Also,  ``alias'' means that the variable is aliased to the same name in
615       capitals.  For example, an assignment to $cdpath  causes  an  automatic
616       assignment  to  $CDPATH,  and vice-versa.  If $CDPATH is set when rc is
617       started, its value is imported into $cdpath.  $cdpath and $path are  rc
618       lists;  $CDPATH  and  $PATH  are colon-separated lists.  Only the names
619       spelt in capitals are exported into the environment.
620
621       * (no-export)
622              The argument list of rc.  $1, $2, etc. are the  same  as  $*(1),
623              $*(2), etc.
624
625       0 (default no-export)
626              The  variable  $0  holds  the value of argv[0] with which rc was
627              invoked.  Additionally, $0 is set to the name of a function  for
628              the  duration  of the execution of that function, and $0 is also
629              set to the name of the file being interpreted for  the  duration
630              of  a  .   command.   $0  is  not an element of $*, and is never
631              treated as one.
632
633       apid (no-export)
634              The process ID of the last process started in the background.
635
636       apids (no-export read-only)
637              A list whose elements are the process IDs of all background pro‐
638              cesses  which  are  still alive, or which have died and have not
639              been waited for yet.
640
641       bqstatus (no-export)
642              The exit status of the rc forked  to  execute  the  most  recent
643              backquote substitution.  Note that, unlike $status, $bqstatus is
644              always a single element list (see EXIT STATUS below).  For exam‐
645              ple:
646
647                   echo foo |grep bar; whatis status
648
649              prints
650
651                   status=(0 1)
652
653              whereas
654
655                   x=`{echo foo |grep bar}; whatis bqstatus
656
657              prints
658
659                   bqstatus=1
660
661       cdpath (alias)
662              A  list of directories to search for the target of a cd command.
663              The empty string stands for the current directory.  Note that if
664              the  $cdpath  variable  does  not contain the current directory,
665              then the current directory will not  be  searched;  this  allows
666              directory  searching to begin in a directory other than the cur‐
667              rent directory.
668
669       history
670              $history contains the name of  a  file  to  which  commands  are
671              appended as rc reads them.  This facilitates the use of a stand-
672              alone history program (such as history(1)) which parses the con‐
673              tents  of  the history file and presents them to rc for reinter‐
674              pretation.  If $history is not set, then rc does not append com‐
675              mands to any file.
676
677       home (alias)
678              The default directory for the builtin cd command, and the direc‐
679              tory in which rc looks to find its initialization  file,  .rcrc,
680              if rc has been started up as a login shell.
681
682       ifs (default)
683              The  internal  field separator, used for splitting up the output
684              of backquote commands for digestion as a list.  On  startup,  rc
685              assigns  the list containing the characters space, tab, and new‐
686              line to $ifs.
687
688       path (alias)
689              This is a list of directories to search in  for  commands.   The
690              empty string stands for the current directory.  If neither $PATH
691              nor $path is set at startup time, $path assumes a default  value
692              suitable  for  your  system.   This is typically (/usr/local/bin
693              /usr/bin /usr/ucb /bin .)
694
695       pid (default no-export)
696              On startup, $pid is initialized to the numeric process ID of the
697              currently running rc.
698
699       prompt (default)
700              This  variable  holds  the two prompts (in list form, of course)
701              that rc prints.  $prompt(1) is printed before  each  command  is
702              read,  and  $prompt(2) is printed when input is expected to con‐
703              tinue on the next line.   rc  sets  $prompt  to  (';  '  '')  by
704              default.   The  reason for this is that it enables an rc user to
705              grab commands from previous lines using a mouse, and to  present
706              them to rc for re-interpretation; the semicolon prompt is simply
707              ignored by rc.  The null $prompt(2) also has its  justification:
708              an   rc   script,  when  typed  interactively,  will  not  leave
709              $prompt(2)'s on the screen, and can therefore be  grabbed  by  a
710              mouse and placed directly into a file for use as a shell script,
711              without further editing being necessary.
712
713       prompt (function)
714              If this function is defined, then it gets executed every time rc
715              is about to print $prompt(1).
716
717       status (no-export read-only)
718              The exit status of the last command.  If the command exited with
719              a numeric value, that number is the status.  If the command died
720              with  a signal, the status is the name of that signal; if a core
721              file was created, the string ``+core'' is appended.   The  value
722              of  $status  for a pipeline is a list, with one entry, as above,
723              for each process in the pipeline.  For example, the command
724
725                   ls | wc
726
727              usually sets $status to (0 0).
728
729       version (default)
730              On startup, the first element of this list variable is  initial‐
731              ized  to a string which identifies this version of rc.  The sec‐
732              ond element is initialized to a string which  can  be  found  by
733              ident(1) and the what command of sccs(1).
734

FUNCTIONS

736       rc  functions  are identical to rc scripts, except that they are stored
737       in memory and are automatically exported into the environment.  A shell
738       function is declared as:
739
740            fn name { commands }
741
742       rc scans the definition until the close-brace, so the function can span
743       more than one line.  The function definition may be removed by typing
744
745            fn name
746
747       (One or more names may be specified.  With an accompanying  definition,
748       all  names  receive  the same definition.  This is sometimes useful for
749       assigning the same signal handler to many signals.  Without  a  defini‐
750       tion,  all  named functions are deleted.)  When a function is executed,
751       $* is set to the arguments to that function for  the  duration  of  the
752       command.   Thus  a  reasonable definition for l, a shorthand for ls(1),
753       could be:
754
755            fn l { ls -FC $* }
756
757       but not
758
759            fn l { ls -FC } # WRONG
760

INTERRUPTS AND SIGNALS

762       rc recognizes a number of signals, and allows the user to define  shell
763       functions  which  act  as  signal handlers.  rc by default traps SIGINT
764       when it is in interactive  mode.   SIGQUIT  and  SIGTERM  are  ignored,
765       unless  rc  has  been  invoked with the -d flag.  However, user-defined
766       signal handlers may be written for these and all  other  signals.   The
767       way  to  define  a signal handler is to write a function by the name of
768       the signal in lower case.  Thus:
769
770            fn sighup { echo hangup; rm /tmp/rc$pid.*; exit }
771
772       In addition to  Unix  signals,  rc  recognizes  the  artificial  signal
773       SIGEXIT which occurs as rc is about to exit.
774
775       In  order  to remove a signal handler's definition, remove it as though
776       it were a regular function.  For example:
777
778            fn sigint
779
780       returns the handler of SIGINT to the default value.  In order to ignore
781       a signal, set the signal handler's value to {}.  Thus:
782
783            fn sigint {}
784
785       causes  SIGINT to be ignored by the shell.  Only signals that are being
786       ignored are passed on to programs run by rc; signal functions  are  not
787       exported.
788
789       On System V-based Unix systems, rc will not allow you to trap SIGCLD.
790

BUILTIN COMMANDS

792       Builtin  commands  execute  in  the context of the shell, but otherwise
793       behave exactly like other commands.   Although  !,  ~  and  @  are  not
794       strictly speaking builtin commands, they can usually be used as such.
795
796       . [-i] file [arg ...]
797              Reads  file as input to rc and executes its contents.  With a -i
798              flag, input is interactive.  Thus from within a shell script,
799
800                   . -i /dev/tty
801
802              does the ``right thing''.
803
804       break  Breaks from the innermost for or while, as in C.  It is an error
805              to invoke break outside of a loop.  (Note that there is no break
806              keyword between commands in switch statements, unlike C.)
807
808       builtin command [arg ...]
809              Executes the command ignoring any  function  definition  of  the
810              same  name.  This command is present to allow functions with the
811              same names as builtins to use the underlying builtin or  binary.
812              For example:
813
814                   fn ls { builtin ls -FC $* }
815
816              is a reasonable way to pass a default set of arguments to ls(1),
817              whereas
818
819                   fn ls { ls -FC $* } # WRONG
820
821              is a non-terminating recursion, which will cause rc  to  exhaust
822              its stack space and (eventually) terminate if it is executed.
823
824       cd [directory]
825              Changes  the  current  directory  to  directory.   The  variable
826              $cdpath is searched for possible locations of directory,  analo‐
827              gous  to  the  searching of $path for executable files.  With no
828              argument, cd changes the current directory to $home.
829
830       echo [-n] [--] [arg ...]
831              Prints its arguments to standard output, terminated  by  a  new‐
832              line.  Arguments are separated by spaces.  If the first argument
833              is -n no final newline is printed.  If the first argument is --,
834              then all other arguments are echoed literally.  This is used for
835              echoing a literal -n.
836
837       eval [list]
838              Concatenates the elements of list  with  spaces  and  feeds  the
839              resulting  string  to rc for re-scanning.  This is the only time
840              input is rescanned in rc.
841
842       exec [arg ...]
843              Replaces rc with the given command.  If the exec  contains  only
844              redirections, then these redirections apply to the current shell
845              and the shell does not exit.  For example,
846
847                   exec >[2] err.out
848
849              places further output to standard error in the file err.out.
850
851       exit [status]
852              Cause the current shell to exit with the given exit status.   If
853              no argument is given, the current value of $status is used.
854
855       limit [-h] [resource [value]]
856              Similar  to the csh(1) limit builtin, this command operates upon
857              the BSD-style resource limits of a process.  The  -h  flag  dis‐
858              plays/alters  the hard limits.  The resources which can be shown
859              or altered are cputime, filesize, datasize, stacksize, coredump‐
860              size,  memoryuse,  and, where supported, descriptors, memoryuse,
861              memoryrss, maxproc, memorylocked, and filelocks.  For example:
862
863                   limit coredumpsize 0
864
865              disables core dumps.  To set a soft  limit  equal  to  the  hard
866              limit:
867
868                   limit `{limit -h datasize}
869
870       newpgrp
871              Puts  rc  into  a new process group.  This builtin is useful for
872              making rc behave like a job-control shell in a hostile  environ‐
873              ment.   One  example is the NeXT Terminal program, which implic‐
874              itly assumes that each shell it forks will put itself into a new
875              process group.
876
877       return [n]
878              Returns  from  the current function, with status n, where n is a
879              valid exit status, or a list of them.  Thus it is legal to have
880
881                   return (sigpipe 1 2 3)
882
883              (This is commonly used to allow a function to  return  with  the
884              exit  status of a previously executed pipeline of commands.)  If
885              n is omitted, then $status is left unchanged.  It is an error to
886              invoke return when not inside a function.
887
888       shift [n]
889              Deletes n elements from the beginning of $* and shifts the other
890              elements down by n.  n defaults to 1.
891
892       umask [mask]
893              Sets the current umask (see umask(2)) to the octal mask.  If  no
894              argument is present, the current mask value is printed.
895
896       wait [pid]
897              Waits  for  process with the specified pid, which must have been
898              started by rc, to exit.  If no pid is specified,  rc  waits  for
899              all its child processes to exit.
900
901       whatis [-b] [-f] [-p] [-s] [-v] [--] [name ...]
902              Prints a definition of the named objects.  For builtins, builtin
903              foo is printed; for functions, including signal handlers,  their
904              definitions  are  printed;  for executable files, path names are
905              printed; and for variables, their values are printed.  The flags
906              restrict  output  to  builtins,  functions, executable programs,
907              signal handlers, and variables, respectively.  If no  names  are
908              specified, rc lists all objects of that type.  (This is not per‐
909              mitted for -p.)  Without  arguments,  whatis  is  equivalent  to
910              whatis  -fv,  and  prints  the values of all shell variables and
911              functions.
912
913              Note that whatis output is suitable for input to rc;  by  saving
914              the  output of whatis in a file, it should be possible to recre‐
915              ate the state of rc by sourcing this file  with  a  .   command.
916              Another note: whatis -s > file cannot be used to store the state
917              of rc's signal handlers in a file, because builtins  with  redi‐
918              rections  are  run  in a subshell, and rc always restores signal
919              handlers to their default value after a fork().
920
921              Since whatis uses getopt(3) to parse its arguments, you can  use
922              the special argument -- to terminate its flags.  This allows you
923              to use names beginning with a dash, such as the history(1)  com‐
924              mands.  For example,
925
926                   whatis -- -p
927

EXAMPLES

929       The shift builtin only shifts $*.  This function can shift any variable
930       (except $lshift).
931
932            fn lshift { lshift=$*; *=$$1; shift $lshift(2); $lshift(1)=$* }
933
934       With this definition in place,
935
936            walrus = (shoes ships sealing-wax cabbages kings)
937            lshift walrus 3
938            whatis walrus
939
940       prints
941
942            walrus=(cabbages kings)
943
944       The $^var operator flattens a list by separating each  element  with  a
945       space.  This function allows the separator to be an arbitrary string.
946
947            fn lflat {
948              lflat=$*; *=$$1
949              while () {
950                echo -n $1; shift
951                ~ $#* 0 && break
952                echo -n $lflat(2)
953            }
954
955       With this definition in place,
956
957            hops=(uunet mcvax ukc tlg)
958            lflat hops !
959
960       prints (with no final newline)
961
962            uunet!mcvax!ukc!tlg
963

EXIT STATUS

965       The  exit status of rc is normally the same as that of the last command
966       executed.  If the last command was a pipeline, rc exits 0 if every com‐
967       mand in the pipeline did; otherwise it exits 1.
968
969       rc can be made to exit with a particular status using the exit builtin.
970

GRAMMAR

972       Here is rc's grammar, edited to remove semantic actions.
973
974            %term ANDAND BACKBACK BANG CASE COUNT DUP ELSE END FLAT FN FOR IF IN
975            %term OROR PIPE REDIR SUB SUBSHELL SWITCH TWIDDLE WHILE WORD HUH
976
977            %left WHILE ')' ELSE
978            %left ANDAND OROR '\n'
979            %left BANG SUBSHELL
980            %left PIPE
981            %right '$'
982            %left SUB
983
984            %start rc
985
986            %%
987
988            rc: line end
989                 | error end
990
991            end: END /* EOF */ | '\n'
992
993            cmdsa: cmd ';' | cmd '&'
994
995            line: cmd | cmdsa line
996
997            body: cmd | cmdsan body
998
999            cmdsan: cmdsa | cmd '\n'
1000
1001            brace: '{' body '}'
1002
1003            paren: '(' body ')'
1004
1005            assign: first '=' word
1006
1007            epilog: /* empty */ | redir epilog
1008
1009            redir: DUP | REDIR word
1010
1011            case: CASE words ';' | CASE words '\n'
1012
1013            cbody: cmd | case cbody | cmdsan cbody
1014
1015            iftail: cmd    %prec ELSE
1016                 | brace ELSE optnl cmd
1017
1018            cmd  : /* empty */  %prec WHILE
1019                 | simple
1020                 | brace epilog
1021                 | IF paren optnl iftail
1022                 | FOR '(' word IN words ')' optnl cmd
1023                 | FOR '(' word ')' optnl cmd
1024                 | WHILE paren optnl cmd
1025                 | SWITCH '(' word ')' optnl '{' cbody '}'
1026                 | TWIDDLE optcaret word words
1027                 | cmd ANDAND optnl cmd
1028                 | cmd OROR optnl cmd
1029                 | cmd PIPE optnl cmd
1030                 | redir cmd    %prec BANG
1031                 | assign cmd   %prec BANG
1032                 | BANG optcaret cmd
1033                 | SUBSHELL optcaret cmd
1034                 | FN words brace
1035                 | FN words
1036
1037            optcaret: /* empty */ | '^'
1038
1039            simple: first | simple word | simple redir
1040
1041            first: comword | first '^' sword
1042
1043            sword: comword | keyword
1044
1045            word: sword | word '^' sword
1046
1047            comword: '$' sword
1048                 | '$' sword SUB words ')'
1049                 | COUNT sword
1050                 | FLAT sword
1051                 | '`' sword
1052                 | '`' brace
1053                 | BACKBACK word     brace | BACKBACK word sword
1054                 | '(' words ')'
1055                 | REDIR brace
1056                 | WORD
1057
1058            keyword: FOR | IN | WHILE | IF | SWITCH
1059                 | FN | ELSE | CASE | TWIDDLE | BANG | SUBSHELL
1060
1061            words: /* empty */ | words word
1062
1063            optnl: /* empty */ | optnl '\n'
1064

FILES

1066       $HOME/.rcrc, /tmp/rc*, /dev/null
1067

CREDITS

1069       rc  was  written by Byron Rakitzis, with valuable help from Paul Haahr,
1070       Hugh Redelmeier and David Sanderson.  The  design  of  this  shell  was
1071       copied from the rc that Tom Duff wrote at Bell Labs.
1072

BUGS

1074       There  is a compile-time limit on the number of ; separated commands in
1075       a line: usually 500.  This is sometimes  a  problem  for  automatically
1076       generated  scripts: substituting the newline character for ; avoids the
1077       limit.
1078
1079       On modern systems that support /dev/fd or /proc/self/fd,  <{foo}  style
1080       redirection  is  implemented that way.  However, on older systems it is
1081       implemented with named pipes.  Allegedly, it is sometimes  possible  to
1082       foil  rc into removing the FIFO it places in /tmp prematurely, or it is
1083       even possible to cause rc to hang.  (The current maintainer  has  never
1084       seen this, but then he doesn't use systems which lack /dev/fd any more.
1085       If anybody can reproduce this problem, please let the maintainer know.)
1086
1087       The echo command does not need to be a builtin.  It is one for  reasons
1088       of performance and portability (of rc scripts).
1089
1090       There should be a way to avoid exporting a variable.
1091
1092       Extra parentheses around a ~ expression or a !  expression are a syntax
1093       error.  Thus, this code is illegal.
1094
1095            while ((~ $1 -*) && (! ~ $1 --)) { ...
1096
1097       The redundant inner parentheses must be omitted.
1098
1099       Variable subscripting cannot be used in here documents.
1100
1101       The limit builtin silently ignores extra arguments.
1102
1103       Backquote substitution never produces empty strings - multiple consecu‐
1104       tive  occurrences  of  the  separator  are treated the same as a single
1105       occurrence.
1106
1107            ifs=! { x = `{echo -n a!!b}; whatis x }
1108            x=(a b) # NOT x=(a '' b)
1109
1110       Bug reports should be mailed to
1111       <toby@paccrat.org>.
1112

INCOMPATIBILITIES

1114       Here is a list of features which distinguish  this  incarnation  of  rc
1115       from the one described in the Bell Labs manual pages:
1116
1117       The  Tenth  Edition  rc does not have the else keyword.  Instead, if is
1118       optionally followed by an if not clause which is executed if  the  pre‐
1119       ceding if test does not succeed.
1120
1121       Backquotes are slightly different in Tenth Edition rc: a backquote must
1122       always be followed by a left-brace.  This restriction  is  not  present
1123       for single-word commands in this rc.
1124
1125       For  .   file,  the  Tenth Edition rc searches $path for file.  This rc
1126       does not, since it is not considered useful.
1127
1128       The list flattening operator, $^foo, is spelt $"foo in  those  versions
1129       of the Bell Labs rc which have it.
1130
1131       The  following  are  all new with this version of rc: The -n flag, here
1132       strings (they facilitate exporting of  functions  with  here  documents
1133       into the environment), the return and break keywords, the echo builtin,
1134       the bqstatus and version variables, the support for the GNU readline(3)
1135       library, and the support for the prompt function.  This rc also sets $0
1136       to the name of a function being executed/file being sourced.
1137

SEE ALSO

1139       ``rc — A Shell for Plan 9 and UNIX  Systems'',  Unix  Research  System,
1140       Tenth Edition, Volume 2. (Saunders College Publishing)
1141
1142       http://static.tobold.org/rc/rc-duff.html,  an  updated  version  of the
1143       above paper.
1144
1145       history(1)
1146
1147
1148
1149                                  2015-05-13                             RC(1)
Impressum