Provided by: rc_1.7.4+97.gceb59bb-5build2_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 any command fails (exits with non-
              zero status). However rc -e does not exit if a conditional fails. A conditional  is
              the test of an if () command, the test of a while () command, or the left hand side
              of the || or the && operator.

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

       The  ~  command succeeds (sets $status to zero) if and only if one of the patterns matches
       subject.  Thus

            ~ foo f*

       succeeds (sets status to zero), while

            ~ bar f*

       fails (sets status to one).

       The null list is matched by the null list, so

            ~ $foo ()

       checks to see whether $foo is empty or not. Because rc does not have  hierarchical  lists,
       the test for emptiness cannot be combined with other tests. To test whether $foo is empty,
       or one of the strings nada or rien, do not write

            ~ $x () nada rien # WRONG means the same as: ~ $x nada rien

       instead write

            ~ $x () || ~ $x nada rien

       Another way to test if $foo is empty is

            ~ $#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

            ~ * ?

       succeeds 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 succeed.  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.

       For compatibility with the Plan 9 rc,

            $"var

       is accepted as a synonym for dollar-caret.

   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 can be used to create shortcuts by defining functions that
       expand to useful argument lists.  For example:

            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.

       As a convenience, rc defines $nl to contain the newline character, and $tab to contain the
       tab character. Thus, if you want to process everything in the current directory, but in  a
       random order, you could use:

            for (f in `` $nl {ls | shuf}) { ... process $f }

       This will correctly handle filenames that contain spaces.

       Note  that  rc scripts that use backquote substitution should avoid relying on the default
       values of $ifs, $nl, or $tab.  Instead, they should explicitly set what they need.

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.

       nl (default)
              Contains the newline character (see Backquote substitution above).

       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).

       tab (default)
              Contains the tab character (see Backquote substitution above).

       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.

       continue
              Continues  the  innermost  for  or  while  loop, as in C.  It is an error to invoke
              continue outside of a loop.

       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.

       flag f [ + | - ]
              Test,  set  (+),  or  reset  (-)  command-line  flag f.  For example, a script that
              requires ``exit if command fails'' semantics can say

                   flag e +

              Some flags cannot be set or reset using flag, but they can still be  tested.  These
              are  c,  d,  l,  o,  p, and s.  As a special case, flag i operates on rc's internal
              interactive flag, which may have been set by -i on the command line, or if standard
              input was a terminal; there is no flag I.

       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.

LINE EDITING

       rc  is  typically  built  against  a line editing library.  On GNU/Linux systems this will
       usually be the GNU readline library.  On *BSD systems it is more  likely  to  be  the  BSD
       editline library.  Please consult the appropriate library documentation for details of how
       to use and configure line editing.

   Tilde Expansion
       Since rc does not support tilde expansion (converting ~foo to the home directory  of  user
       foo),  it  is  sometimes  suggested  by  users as a possible enhancement.  The authors and
       maintainers of rc have a proud history of resisting such feature requests.  So it is worth
       noting  here  that  GNU readline can expand tildes.  Add this line to the file .inputrc in
       your home directory.

            set expand-tilde on

       and then use the key sequence M-~ to perform tilde expansion on the current word.  See the
       readline documentation for further details.

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 '^' '='
            %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 optcaret '=' optcaret 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 */ %prec '^' | '^'

            simple: first | first args

            args: arg | args arg

            arg: word | 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.

       Backquote substitution never produces empty strings - multiple consecutive occurrences  of
       the separator are treated the same as a single occurrence.

            ifs=! { x = `{echo -n a!!b}; whatis x }
            x=(a b) # NOT x=(a '' b)

       Bug reports should be mailed to
       <toby@paccrat.org>.

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  prompt
       function, support for GNU readline and other line editing libraries.  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://static.tobold.org/rc/rc-duff.html, an updated version of the above paper.

       history(1)

                                            2015-05-13                                      RC(1)