Provided by: rc_1.7.1-5_amd64 bug

NAME

       rc - shell

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

       -c     If  -c  is  present, commands are executed from the immediately following argument.
              Any further arguments to rc are placed in $*.  Thus:

                   rc -c 'echo $*' 1 2 3

              prints out

                   1 2 3

       -d     This flag causes rc not to ignore SIGQUIT or SIGTERM.  Thus rc can be made to  dump
              core if sent SIGQUIT.  This flag is only useful for debugging rc.

       -e     If  the  -e  flag  is present, then rc will exit if the exit status of a command is
              false (nonzero).  rc will not exit, however, if a conditional fails, e.g., an  if()
              command.

       -i     If  the  -i flag is present or if the input to rc is from a terminal (as determined
              by isatty(3)) then rc will be  in  interactive  mode.   That  is,  a  prompt  (from
              $prompt(1))  will  be  printed  before  an  input line is taken, and rc will ignore
              SIGINT.

       -I     If the -I flag is present, or if the input to rc is not from a  terminal,  then  rc
              will not be in interactive mode.  No prompts will be printed, and SIGINT will cause
              rc to exit.

       -l     If the -l flag is present, or if rc's argv[0][0] is a dash (-), then rc will behave
              as  a  login  shell.   That is, it will run commands from $home/.rcrc, if this file
              exists, before reading any other input.

       -n     This flag causes rc to read its  input  and  parse  it,  but  not  to  execute  any
              commands.   This  is useful for syntax checking on scripts.  If used in combination
              with the -x flag, rc will print each command as it is parsed in a form  similar  to
              the one used for exporting functions into the environment.

       -o     This  flag  prevents  the  usual  practice  of  trying  to  open  /dev/null on file
              descriptors 0, 1, and 2, if any of those descriptors are inherited closed.

       -p     This flag prevents rc from initializing shell functions from the environment.  This
              allows  rc  to run in a protected mode, whereby it becomes more difficult for an rc
              script to be subverted by placing false commands in the  environment.   (Note  that
              the  presence  of this flag does not mean that it is safe to run setuid rc scripts;
              the usual caveats about the setuid bit still apply.)

       -s     This flag causes rc to read from standard input.  Any arguments are placed in $*.

       -v     This flag causes rc to echo its input to standard error as it is read.

       -x     This flag causes rc to print every command on standard error before it is executed.
              It can be useful for debugging rc scripts.

COMMANDS

       A  simple  command  is  a  sequence  of  words,  separated  by white space (space and tab)
       characters that ends with a newline, semicolon (;), or ampersand (&).  The first word of a
       command is the name of that command.  If the name begins with /, ./, or ../, then the name
       is used as an absolute path name referring to an executable file.  Otherwise, the name  of
       the  command is looked up in a table of shell functions, builtin commands, or as a file in
       the directories named by $path.

   Background Tasks
       A command ending with & is run in the background; that is, the shell  returns  immediately
       rather  than  waiting  for  the  command  to complete.  Background commands have /dev/null
       connected to their standard input unless an explicit redirection  for  standard  input  is
       used.

   Subshells
       A  command  prefixed  with  an  at-sign (@) is executed in a subshell.  This insulates the
       parent shell from the effects of state changing operations such as  a  cd  or  a  variable
       assignment.  For example:

            @ {cd ..; make}

       will run make(1) in the parent directory (..), but leaves the shell running in the current
       directory.

   Line continuation
       A long logical line may be continued over several physical lines by terminating each  line
       (except  the  last)  with a backslash (\).  The backslash-newline sequence is treated as a
       space.  A backslash is not otherwise  special  to  rc.   (In  addition,  inside  quotes  a
       backslash loses its special meaning even when it is followed by a newline.)

   Quoting
       rc  interprets  several  characters  specially; special characters automatically terminate
       words.  The following characters are special:

            # ; & | ^ $ = ` ' { } ( ) < >

       The single quote (') prevents special treatment of any character other than  itself.   All
       characters,  including  control  characters,  newlines,  and backslashes between two quote
       characters are treated as an uninterpreted string.  A quote character itself may be quoted
       by  placing two quotes in a row.  The minimal sequence needed to enter the quote character
       is ''''.  The empty string is represented by ''.  Thus:

            echo 'What''s the plan, Stan?'

       prints out

            What's the plan, Stan?

       The number sign (#) begins a comment in rc.  All characters up to but  not  including  the
       next  newline  are  ignored.   Note  that  backslash  continuation  does not work inside a
       comment, i.e., the backslash is ignored along with everything else.

   Grouping
       Zero or more commands may be grouped within braces (“{” and “}”), and are then treated  as
       one  command.   Braces  do  not  otherwise  define  scope;  they are used only for command
       grouping.  In particular, be wary of the command:

            for (i) {
                command
            } | command

       Since pipe binds tighter than for, this command does not perform what the user expects  it
       to.  Instead, enclose the whole for statement in braces:

            {for (i) command} | command

       Fortunately,  rc's  grammar  is simple enough that a (confident) user can understand it by
       examining the skeletal yacc(1) grammar at the end  of  this  man  page  (see  the  section
       entitled GRAMMAR).

   Input and output
       The standard output may be redirected to a file with

            command > file

       and the standard input may be taken from a file with

            command < file

       Redirections can appear anywhere in the line: the word following the redirection symbol is
       the filename and must be quoted if it contains spaces or other special characters.   These
       are all equivalent.

            echo 1 2 3 > foo
            > foo echo 1 2 3
            echo 1 2 > foo 3

       File  descriptors  other  than  0  and  1 may be specified also.  For example, to redirect
       standard error to a file, use:

            command >[2] file

       In order to duplicate a file descriptor, use  >[n=m].   Thus  to  redirect  both  standard
       output and standard error to the same file, use

            command > file >[2=1]

       As in sh, redirections are processed from left to right.  Thus this sequence

            command >[2=1] > file

       is  usually  a  mistake.   It  first  duplicates  standard  error to standard output; then
       redirects standard output to a file,  leaving  standard  error  wherever  standard  output
       originally was.

       To  close  a  file  descriptor  that  may  be open, use >[n=].  For example, to close file
       descriptor 7:

            command >[7=]

       Note that no spaces may appear in these constructs:

            command > [2] file

       would send the output of the command to a file  named  [2],  with  the  intended  filename
       appearing in the command's argument list.

       In order to place the output of a command at the end of an already existing file, use:

            command >> file

       If the file does not exist, then it is created.

       “Here documents” are supported as in sh with the use of

            command << 'eof-marker'

       Subsequent  lines  form the standard input of the command, till a line containing just the
       marker, in this case eof-marker, is encountered.

       If the end-of-file marker is enclosed in quotes,  then  no  variable  substitution  occurs
       inside  the  here  document.   Otherwise,  every  variable  is  substituted  by its space-
       separated-list value (see Flat Lists, below), and if a  ^  character  follows  a  variable
       name, it is deleted.  This allows the unambiguous use of variables adjacent to text, as in

            $variable^follow

       To  include  a  literal  $ in a here document when an unquoted end-of-file marker is being
       used, enter it as $$.

       Additionally, rc supports “here strings”, which are like here documents, except that input
       is taken directly from a string on the command line.  Their use is illustrated here:

            cat <<< 'this is a here string' | wc

       (This  feature  enables  rc to export functions using here documents into the environment;
       the author does not expect users to find this feature useful.)

   Pipes
       Two or more commands may be combined in a pipeline by placing the vertical bar (|) between
       them.   The  standard output (file descriptor 1) of the command on the left is tied to the
       standard input (file descriptor 0) of the command  on  the  right.   The  notation  |[n=m]
       indicates  that file descriptor n of the left process is connected to file descriptor m of
       the right process.  |[n] is a shorthand for |[n=0].  As an example, to pipe  the  standard
       error of a command to wc(1), use:

            command |[2] wc

       As  with  file redirections, no spaces may occur in the construct specifying numbered file
       descriptors.

       The exit status of a pipeline is considered true if and  only  if  every  command  in  the
       pipeline exits true.

   Commands as Arguments
       Some  commands,  like  cmp(1) or diff(1), take their arguments on the command line, and do
       not read input from standard  input.   It  is  convenient  sometimes  to  build  nonlinear
       pipelines  so  that  a command like cmp can read the output of two other commands at once.
       rc does it like this:

            cmp <{command} <{command}

       compares the output of the two commands in braces.  Note: since this form  of  redirection
       is  implemented  with some kind of pipe, and since one cannot lseek(2) on a pipe, commands
       that use lseek(2) will hang.  For example, some versions of diff(1) use lseek(2) on  their
       inputs.

       Data  can  be  sent down a pipe to several commands using tee(1) and the output version of
       this notation:

            echo hi there | tee >{sed 's/^/p1 /'} >{sed 's/^/p2 /'}

CONTROL STRUCTURES

       The following may be used for control flow in rc:

   If-Else Statements
       if (test) {
           cmd
       } else cmd
              The test is executed, and if its return  status  is  zero,  the  first  command  is
              executed,  otherwise  the second is.  Braces are not mandatory around the commands.
              However, an else statement is valid only if it follows a close-brace  on  the  same
              line.  Otherwise, the if is taken to be a simple-if:

                   if (test)
                       command

   While and For Loops
       while (test) cmd
              rc executes the test and performs the command as long as the test is true.

       for (var in list) cmd
              rc  sets  var  to  each  element of list (which may contain variables and backquote
              substitutions) and runs cmd.  If “in list” is omitted, then rc will set var to each
              element of $*.  For example:

                   for (i in `{ls -F | grep '\*$' | sed 's/\*$//'}) { commands }

              will set $i to the name of each file in the current directory that is executable.

   Switch
       switch (list) { case ... }
              rc  looks  inside  the braces after a switch for statements beginning with the word
              case.  If any of the patterns following case match the  list  supplied  to  switch,
              then   the   commands   up  until  the  next  case  statement  are  executed.   The
              metacharacters *, [ or ?  should not be quoted; matching is performed only  against
              the  strings in list, not against file names.  (Matching for case statements is the
              same as for the ~ command.)

   Logical Operators
       There are a number of operators in rc which depend on the exit status of a command.

            command && command

       executes the first command and then executes the second command if and only if  the  first
       command exits with a zero exit status (“true” in Unix).

            command || command

       executes  the  first command and then executes the second command if and only if the first
       command exits with a nonzero exit status (“false” in Unix).

            ! command

       negates the exit status of a command.

PATTERN MATCHING

       There are two forms of pattern matching in rc.  One is traditional shell  globbing.   This
       occurs in matching for file names in argument lists:

            command argument argument ...

       When  the  characters *, [ or ?  occur in an argument or command, rc looks at the argument
       as a pattern for matching against files.  (Contrary to the behavior other shells  exhibit,
       rc  will only perform pattern matching if a metacharacter occurs unquoted and literally in
       the input.  Thus,

            foo='*'
            echo $foo

       will always echo just a star.  In order for non-literal metacharacters to be expanded,  an
       eval  statement  must  be  used  in  order  to rescan the input.)  Pattern matching occurs
       according to the following rules: a * matches any number (including zero)  of  characters.
       A  ?  matches any single character, and a [ followed by a number of characters followed by
       a ] matches a single character in that class.  The rules for character class matching  are
       the  same as those for ed(1), with the exception that character class negation is achieved
       with the tilde (~), not the caret (^), since the caret already means something else in rc.

       rc also matches patterns against strings with the ~ command:

            ~ subject pattern pattern ...

       ~ sets $status to zero if and only if a supplied pattern matches any single element of the
       subject list.  Thus

            ~ foo f*

       sets status to zero, while

            ~ (bar baz) f*

       sets status to one.  The null list is matched by the null list, so

            ~ $foo ()

       checks to see whether $foo is empty or not.  This may also be achieved by the test

            ~ $#foo 0

       Note  that  inside a ~ command rc does not match patterns against file names, so it is not
       necessary to quote the characters *, [ and ?.  However, rc does expand the subject against
       filenames if it contains metacharacters.  Thus, the command

            ~ * ?

       returns  true  if  any of the files in the current directory have a single-character name.
       If the ~ command is given a list as its first argument, then a  successful  match  against
       any of the elements of that list will cause ~ to return true.  For example:

            ~ (foo goo zoo) z*

       is true.

LISTS AND VARIABLES

       The  primary  data structure in rc is the list, which is a sequence of words.  Parentheses
       are used to group lists.  The empty list is represented by ().  Lists have no hierarchical
       structure;  a  list  inside  another  list  is expanded so the outer list contains all the
       elements of the inner list.  Thus, the following are all equivalent

            one two three

            (one two three)

            ((one) () ((two three)))

       Note that the null string, '', and the null list,  (),  are  two  very  different  things.
       Assigning  the  null string to a variable is a valid operation, but it does not remove its
       definition.

            null = '' empty = () echo $#null $#empty

       produces the output

            1 0

   List Concatenation
       Two lists may be joined by the concatenation operator (^).  Concatenation works  according
       to  the  following  rules:  if  the  two  lists  have  the  same  number of elements, then
       concatenation is pairwise:

            echo (a- b- c-)^(1 2 3)

       produces the output

            a-1 b-2 c-3

       Otherwise, at  least  one  of  the  lists  must  have  a  single  element,  and  then  the
       concatenation is distributive:

            cc -^(O g c) (malloc alloca)^.c

       has the effect of performing the command

            cc -O -g -c malloc.c alloca.c

       A single word is a list of length one, so

            echo foo^bar

       produces the output

            foobar

   Free Carets
       rc  inserts  carets  (concatenation operators) for free in certain situations, in order to
       save some typing on the user's behalf.  For example, the above example could also be typed
       in as:

            opts=(O g c) files=(malloc alloca) cc -$opts $files.c

       rc  takes care to insert a free-caret between the “-” and $opts, as well as between $files
       and .c.  The rule for free carets is as follows:  if a  word  or  keyword  is  immediately
       followed  by  another  word,  keyword,  dollar-sign  or backquote, then rc inserts a caret
       between them.

   Variables
       A list may be assigned to a variable, using the notation:

            var = list

       The special variable * may also be assigned to using this notation; rc has no set builtin.

       Any non-empty sequence of characters, except a sequence including only digits, may be used
       as  a  variable  name.  Any character except = may be used, but special characters must be
       quoted.  All user-defined variables are exported into the environment.

       The value of a variable is referenced with the dollar ($) operator:

            $var

       Any variable which has not  been  assigned  a  value  returns  the  null  list,  (),  when
       referenced.  Multiple references are allowed:

            a = foo
            b = a
            echo $ $ b

       prints

            foo

       A variable's definition may also be removed by assigning the null list to a variable:

            var=()

       For  “free  careting”  to  work  correctly,  rc  must  make certain assumptions about what
       characters may appear in a variable name.  rc assumes that a variable name  consists  only
       of  alphanumeric  characters,  underscore  (_) and star (*).  To reference a variable with
       other characters in its name, quote the variable name.  Thus:

            echo $'we$Ird:Variab!le'

   Local Variables
       Any number of variable assignments may be made local to a single command by typing:

            a=foo b=bar ... command

       The command may be a compound command, so for example:

            path=. ifs=() {
                ...
            }

       sets path to .  and removes ifs for the duration of one long compound command.

   Variable Subscripts
       Variables may be subscripted with the notation

            $var(n)

       where n is a list of integers (origin 1).  The opening parenthesis must immediately follow
       the variable name.  The list of subscripts need not be in order or even unique.  Thus,

            a=(one two three)
            echo $a(3 3 3)

       prints

            three three three

       If  n  references a nonexistent element, then $var(n) returns the null list.  The notation
       $n, where n is an integer, is a shorthand for $*(n).  Thus, rc's arguments may be referred
       to as $1, $2, and so on.

       Note also that the list of subscripts may be given by any of rc's list operations:

            $var(`{awk 'BEGIN{for(i=1;i<=10;i++)print i;exit; }'})

       returns the first 10 elements of $var.

       To count the number of elements in a variable, use

            $#var

       This returns a single-element list, with the number of elements in $var.

   Flat Lists
       In  order  to  create a single-element list from a multi-element list, with the components
       space-separated, use the dollar-caret ($^) operator:

            $^var

       This is useful when the normal list concatenation rules need to be bypassed.  For example,
       to append a single period at the end of $path, use:

            echo $^path.

   Backquote Substitution
       A list may be formed from the output of a command by using backquote substitution:

            `{ command }

       returns  a list formed from the standard output of the command in braces.  $ifs is used to
       split the output into list elements.  By default, $ifs has  the  value  space-tab-newline.
       The  braces  may be omitted if the command is a single word.  Thus `ls may be used instead
       of `{ls}.  This last feature is useful when  defining  functions  that  expand  to  useful
       argument lists.  A frequent use is:

            fn src { echo *.[chy] }

       followed by

            wc `src

       (This will print out a word-count of all C source files in the current directory.)

       In order to override the value of $ifs for a single backquote substitution, use:

            `` (ifs-list) { command }

       $ifs  will  be  temporarily ignored and the command's output will be split as specified by
       the list following the double backquote.  For example:

            `` ($nl :) {cat /etc/passwd}

       splits up /etc/passwd into fields, assuming that $nl contains a newline as its value.

SPECIAL VARIABLES

       Several variables are known to rc and are  treated  specially.   In  the  following  list,
       “default”  indicates  that  rc  gives the variable a default value on startup; “no-export”
       indicates that the variable is never exported; and “read-only” indicates that  an  attempt
       to set the variable will silently have no effect.

       Also,  “alias”  means  that  the  variable  is  aliased to the same name in capitals.  For
       example, an assignment to $cdpath causes an automatic assignment  to  $CDPATH,  and  vice-
       versa.  If $CDPATH is set when rc is started, its value is imported into $cdpath.  $cdpath
       and $path are rc lists; $CDPATH and $PATH are colon-separated lists.  Only the names spelt
       in capitals are exported into the environment.

       * (no-export)
              The argument list of rc.  $1, $2, etc. are the same as $*(1), $*(2), etc.

       0 (default no-export)
              The   variable   $0  holds  the  value  of  argv[0]  with  which  rc  was  invoked.
              Additionally, $0 is set to the name of a function for the duration of the execution
              of  that function, and $0 is also set to the name of the file being interpreted for
              the duration of a .  command.  $0 is not an element of $*, and is never treated  as
              one.

       apid (no-export)
              The process ID of the last process started in the background.

       apids (no-export read-only)
              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.

       bqstatus (no-export)
              The exit status of the rc forked to execute the most recent backquote substitution.
              Note  that,  unlike  $status,  $bqstatus  is always a single element list (see EXIT
              STATUS below).  For example:

                   echo foo |grep bar; whatis status

              prints

                   status=(0 1)

              whereas

                   x=`{echo foo |grep bar}; whatis bqstatus

              prints

                   bqstatus=1

       cdpath (alias)
              A list of directories to search for the target of a cd command.  The  empty  string
              stands  for  the  current  directory.   Note  that if the $cdpath variable does not
              contain the current directory, then the current directory  will  not  be  searched;
              this  allows  directory  searching  to  begin in a directory other than the current
              directory.

       history
              $history contains the name of a file to which commands are  appended  as  rc  reads
              them.   This  facilitates  the  use  of  a  stand-alone  history  program  (such as
              history(1)) which parses the contents of the history file and presents them  to  rc
              for  reinterpretation.  If $history is not set, then rc does not append commands to
              any file.

       home (alias)
              The default directory for the builtin cd command, and the  directory  in  which  rc
              looks  to find its initialization file, .rcrc, if rc has been started up as a login
              shell.

       ifs (default)
              The internal field separator,  used  for  splitting  up  the  output  of  backquote
              commands  for  digestion as a list.  On startup, rc assigns the list containing the
              characters space, tab, and newline to $ifs.

       path (alias)
              This is a list of directories to search in for commands.  The empty  string  stands
              for  the  current  directory.   If  neither $PATH nor $path is set at startup time,
              $path assumes a  default  value  suitable  for  your  system.   This  is  typically
              (/usr/local/bin /usr/bin /usr/ucb /bin .)

       pid (default no-export)
              On  startup, $pid is initialized to the numeric process ID of the currently running
              rc.

       prompt (default)
              This variable holds the two prompts (in list  form,  of  course)  that  rc  prints.
              $prompt(1)  is  printed before each command is read, and $prompt(2) is printed when
              input is expected to continue on the next line.  rc sets $prompt to (';  '  '')  by
              default.   The  reason for this is that it enables an rc user to grab commands from
              previous lines using a mouse, and to present them to rc for re-interpretation;  the
              semicolon  prompt  is  simply  ignored  by  rc.   The  null $prompt(2) also has its
              justification:  an rc script, when typed interactively, will not leave $prompt(2)'s
              on  the  screen, and can therefore be grabbed by a mouse and placed directly into a
              file for use as a shell script, without further editing being necessary.

       prompt (function)
              If this function is defined, then it gets executed every time rc is about to  print
              $prompt(1).

       status (no-export read-only)
              The  exit  status of the last command.  If the command exited with a numeric value,
              that number is the status.  If the command died with a signal, the  status  is  the
              name  of  that  signal; if a core file was created, the string “+core” is appended.
              The value of $status for a pipeline is a list, with one entry, as above,  for  each
              process in the pipeline.  For example, the command

                   ls | wc

              usually sets $status to (0 0).

       version (default)
              On  startup,  the  first  element  of this list variable is initialized to a string
              which identifies this version of rc.  The second element is initialized to a string
              which can be found by ident(1) and the what command of sccs(1).

FUNCTIONS

       rc  functions  are  identical to rc scripts, except that they are stored in memory and are
       automatically exported into the environment.  A shell function is declared as:

            fn name { commands }

       rc scans the definition until the close-brace, so the function  can  span  more  than  one
       line.  The function definition may be removed by typing

            fn name

       (One  or  more names may be specified.  With an accompanying definition, all names receive
       the same definition.  This is sometimes useful for assigning the same  signal  handler  to
       many signals.  Without a definition, all named functions are deleted.)  When a function is
       executed, $* is set to the arguments to that function for the  duration  of  the  command.
       Thus a reasonable definition for l, a shorthand for ls(1), could be:

            fn l { ls -FC $* }

       but not

            fn l { ls -FC } # WRONG

INTERRUPTS AND SIGNALS

       rc recognizes a number of signals, and allows the user to define shell functions which act
       as signal handlers.  rc by default traps SIGINT when it is in interactive  mode.   SIGQUIT
       and  SIGTERM  are  ignored,  unless  rc has been invoked with the -d flag.  However, user-
       defined signal handlers may be written for these and all other signals.  The way to define
       a signal handler is to write a function by the name of the signal in lower case.  Thus:

            fn sighup { echo hangup; rm /tmp/rc$pid.*; exit }

       In  addition  to Unix signals, rc recognizes the artificial signal SIGEXIT which occurs as
       rc is about to exit.

       In order to remove a signal handler's definition, remove it as though it  were  a  regular
       function.  For example:

            fn sigint

       returns  the handler of SIGINT to the default value.  In order to ignore a signal, set the
       signal handler's value to {}.  Thus:

            fn sigint {}

       causes SIGINT to be ignored by the shell.  Only signals that are being ignored are  passed
       on to programs run by rc; signal functions are not exported.

       On System V-based Unix systems, rc will not allow you to trap SIGCLD.

BUILTIN COMMANDS

       Builtin  commands  execute  in the context of the shell, but otherwise behave exactly like
       other commands.  Although !, ~ and @ are not strictly speaking builtin commands, they  can
       usually be used as such.

       . [-i] file [arg ...]
              Reads  file  as  input  to  rc and executes its contents.  With a -i flag, input is
              interactive.  Thus from within a shell script,

                   . -i /dev/tty

              does the “right thing”.

       break  Breaks from the innermost for or while, as in C.  It is an error  to  invoke  break
              outside of a loop.  (Note that there is no break keyword between commands in switch
              statements, unlike C.)

       builtin command [arg ...]
              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:

                   fn ls { builtin ls -FC $* }

              is a reasonable way to pass a default set of arguments to ls(1), whereas

                   fn ls { ls -FC $* } # WRONG

              is a non-terminating recursion, which will cause rc to exhaust its stack space  and
              (eventually) terminate if it is executed.

       cd [directory]
              Changes  the  current directory to directory.  The variable $cdpath is searched for
              possible locations of directory, analogous to the searching of $path for executable
              files.  With no argument, cd changes the current directory to $home.

       echo [-n] [--] [arg ...]
              Prints  its  arguments  to standard output, terminated by a newline.  Arguments are
              separated by spaces.  If the first argument is -n no final newline is printed.   If
              the  first  argument is --, then all other arguments are echoed literally.  This is
              used for echoing a literal -n.

       eval [list]
              Concatenates the elements of list with spaces and feeds the resulting string to  rc
              for re-scanning.  This is the only time input is rescanned in rc.

       exec [arg ...]
              Replaces  rc  with the given command.  If the exec contains only redirections, then
              these redirections apply to the current shell and the shell  does  not  exit.   For
              example,

                   exec >[2] err.out

              places further output to standard error in the file err.out.

       exit [status]
              Cause  the  current  shell  to  exit with the given exit status.  If no argument is
              given, the current value of $status is used.

       limit [-h] [resource [value]]
              Similar to the csh(1) limit builtin,  this  command  operates  upon  the  BSD-style
              resource  limits  of  a process.  The -h flag displays/alters the hard limits.  The
              resources which can be shown or altered are cputime, filesize, datasize, stacksize,
              coredumpsize,  memoryuse,  and, where supported, descriptors, memoryuse, memoryrss,
              maxproc, memorylocked, and filelocks.  For example:

                   limit coredumpsize 0

              disables core dumps.  To set a soft limit equal to the hard limit:

                   limit `{limit -h datasize}

       newpgrp
              Puts rc into a new process group.  This builtin is useful for making rc behave like
              a  job-control  shell  in  a hostile environment.  One example is the NeXT Terminal
              program, which implicitly assumes that each shell it forks will put itself  into  a
              new process group.

       return [n]
              Returns  from  the current function, with status n, where n is a valid exit status,
              or a list of them.  Thus it is legal to have

                   return (sigpipe 1 2 3)

              (This is commonly used to allow a function to return with  the  exit  status  of  a
              previously  executed  pipeline of commands.)  If n is omitted, then $status is left
              unchanged.  It is an error to invoke return when not inside a function.

       shift [n]
              Deletes n elements from the beginning of $* and shifts the other elements  down  by
              n.  n defaults to 1.

       umask [mask]
              Sets  the  current  umask  (see  umask(2))  to  the  octal mask.  If no argument is
              present, the current mask value is printed.

       wait [pid]
              Waits for process with the specified pid, which must have been started  by  rc,  to
              exit.  If no pid is specified, rc waits for all its child processes to exit.

       whatis [-b] [-f] [-p] [-s] [-v] [--] [name ...]
              Prints  a  definition  of the named objects.  For builtins, builtin foo is printed;
              for functions, including  signal  handlers,  their  definitions  are  printed;  for
              executable  files,  path  names  are  printed;  and for variables, their values are
              printed.  The flags restrict output to builtins,  functions,  executable  programs,
              signal  handlers, and variables, respectively.  If no names are specified, rc lists
              all objects of that type.  (This is not  permitted  for  -p.)   Without  arguments,
              whatis  is  equivalent  to whatis -fv, and prints the values of all shell variables
              and functions.

              Note that whatis output is suitable for input to rc; by saving the output of whatis
              in  a file, it should be possible to recreate the state of rc by sourcing this file
              with a .  command.  Another note: whatis -s > file cannot  be  used  to  store  the
              state of rc's signal handlers in a file, because builtins with redirections are run
              in a subshell, and rc always restores signal handlers to their default value  after
              a fork().

              Since  whatis  uses  getopt(3)  to  parse  its  arguments,  you can use the special
              argument -- to terminate its flags.  This allows you to use names beginning with  a
              dash, such as the history(1) commands.  For example,

                   whatis -- -p

EXAMPLES

       The shift builtin only shifts $*.  This function can shift any variable (except $lshift).

            fn lshift { lshift=$*; *=$$1; shift $lshift(2); $lshift(1)=$* }

       With this definition in place,

            walrus = (shoes ships sealing-wax cabbages kings)
            lshift walrus 3
            whatis walrus

       prints

            walrus=(cabbages kings)

       The $^var operator flattens a list by separating each element with a space.  This function
       allows the separator to be an arbitrary string.

            fn lflat {
              lflat=$*; *=$$1
              while () {
                echo -n $1; shift
                ~ $#* 0 && break
                echo -n $lflat(2)
            }

       With this definition in place,

            hops=(uunet mcvax ukc tlg)
            lflat hops !

       prints (with no final newline)

            uunet!mcvax!ukc!tlg

EXIT STATUS

       The exit status of rc is normally the same as that of the last command executed.   If  the
       last command was a pipeline, rc exits 0 if every command in the pipeline did; otherwise it
       exits 1.

       rc can be made to exit with a particular status using the exit builtin.

GRAMMAR

       Here is rc's grammar, edited to remove semantic actions.

            %term ANDAND BACKBACK BANG CASE COUNT DUP ELSE END FLAT FN FOR IF IN
            %term OROR PIPE REDIR SUB SUBSHELL SWITCH TWIDDLE WHILE WORD HUH

            %left WHILE ')' ELSE
            %left ANDAND OROR '\n'
            %left BANG SUBSHELL
            %left PIPE
            %right '$'
            %left SUB

            %start rc

            %%

            rc: line end
                 | error end

            end: END /* EOF */ | '\n'

            cmdsa: cmd ';' | cmd '&'

            line: cmd | cmdsa line

            body: cmd | cmdsan body

            cmdsan: cmdsa | cmd '\n'

            brace: '{' body '}'

            paren: '(' body ')'

            assign: first '=' word

            epilog: /* empty */ | redir epilog

            redir: DUP | REDIR word

            case: CASE words ';' | CASE words '\n'

            cbody: cmd | case cbody | cmdsan cbody

            iftail: cmd    %prec ELSE
                 | brace ELSE optnl cmd

            cmd  : /* empty */  %prec WHILE
                 | simple
                 | brace epilog
                 | IF paren optnl iftail
                 | FOR '(' word IN words ')' optnl cmd
                 | FOR '(' word ')' optnl cmd
                 | WHILE paren optnl cmd
                 | SWITCH '(' word ')' optnl '{' cbody '}'
                 | TWIDDLE optcaret word words
                 | cmd ANDAND optnl cmd
                 | cmd OROR optnl cmd
                 | cmd PIPE optnl cmd
                 | redir cmd    %prec BANG
                 | assign cmd   %prec BANG
                 | BANG optcaret cmd
                 | SUBSHELL optcaret cmd
                 | FN words brace
                 | FN words

            optcaret: /* empty */ | '^'

            simple: first | simple word | simple redir

            first: comword | first '^' sword

            sword: comword | keyword

            word: sword | word '^' sword

            comword: '$' sword
                 | '$' sword SUB words ')'
                 | COUNT sword
                 | FLAT sword
                 | '`' sword
                 | '`' brace
                 | BACKBACK word     brace | BACKBACK word sword
                 | '(' words ')'
                 | REDIR brace
                 | WORD

            keyword: FOR | IN | WHILE | IF | SWITCH
                 | FN | ELSE | CASE | TWIDDLE | BANG | SUBSHELL

            words: /* empty */ | words word

            optnl: /* empty */ | optnl '\n'

FILES

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

CREDITS

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

BUGS

       There is a compile-time limit on the number of ; separated commands  in  a  line:  usually
       500.   This  is  sometimes a problem for automatically generated scripts: substituting the
       newline character for ; avoids the limit.

       On modern systems that support /dev/fd  or  /proc/self/fd,  <{foo}  style  redirection  is
       implemented  that  way.   However,  on  older  systems it is implemented with named pipes.
       Allegedly, it is sometimes possible to foil rc into removing the FIFO it  places  in  /tmp
       prematurely,  or  it  is  even  possible to cause rc to hang.  (The current maintainer has
       never seen this, but then he doesn't use systems which lack /dev/fd any more.  If  anybody
       can reproduce this problem, please let the maintainer know.)

       The  echo command does not need to be a builtin.  It is one for reasons of performance and
       portability (of rc scripts).

       There should be a way to avoid exporting a variable.

       Extra parentheses around a ~ expression or a !  expression are a syntax error.  Thus, this
       code is illegal.

            while ((~ $1 -*) && (! ~ $1 --)) { ...

       The redundant inner parentheses must be omitted.

       Variable subscripting cannot be used in here documents.

       The limit builtin silently ignores extra arguments.

       Bug reports should be mailed to <tjg@star.le.ac.uk>.

INCOMPATIBILITIES

       Here is a list of features which distinguish this incarnation of rc from the one described
       in the Bell Labs manual pages:

       The Tenth Edition rc does not have the else keyword.  Instead, if is  optionally  followed
       by an if not clause which is executed if the preceding if test does not succeed.

       Backquotes are slightly different in Tenth Edition rc: a backquote must always be followed
       by a left-brace.  This restriction is not present for single-word commands in this rc.

       For .  file, the Tenth Edition rc searches $path for file.  This rc does not, since it  is
       not considered useful.

       The  list flattening operator, $^foo, is spelt $"foo in those versions of the Bell Labs rc
       which have it.

       The following are all new with this version  of  rc:  The  -n  flag,  here  strings  (they
       facilitate  exporting  of  functions with here documents into the environment), the return
       and break keywords, the echo builtin, the bqstatus and version variables, the support  for
       the  GNU  readline(3) library, and the support for the prompt function.  This rc also sets
       $0 to the name of a function being executed/file being sourced.

SEE ALSO

       “rc — A Shell for Plan 9 and UNIX Systems”, Unix Research System, Tenth Edition, Volume 2.
       (Saunders College Publishing)

       http://www.star.le.ac.uk/~tjg/rc/misc/td, an updated version of the above paper.

       history(1)

                                            2003-07-17                                      RC(1)