Provided by: 9base_6-11_amd64 bug

NAME

       rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ - command language

SYNOPSIS

       rc [ -srdiIlxepvV ] [ -c command ] [ file [ arg ...  ]]

DESCRIPTION

       Rc is the Plan 9 shell.  It executes command lines read from a terminal or a file or, with
       the -c flag, from rc's argument list.

   Command Lines
       A command line is a sequence of commands, separated by ampersands or semicolons (& or  ;),
       terminated  by  a  newline.  The commands are executed in sequence from left to right.  Rc
       does not wait for a command  followed  by  &  to  finish  executing  before  starting  the
       following  command.   Whenever  a  command  followed  by  & is executed, its process id is
       assigned to the rc variable $apid.  Whenever a command not  followed  by  &  exits  or  is
       terminated, the rc variable $status gets the process's wait message (see wait(3)); it will
       be the null string if the command was successful.

       A long command line may be continued  on  subsequent  lines  by  typing  a  backslash  (\)
       followed  by a newline.  This sequence is treated as though it were a blank.  Backslash is
       not otherwise a special character.

       A number-sign (#) and any following characters up to (but not including) the next  newline
       are ignored, except in quotation marks.

   Simple Commands
       A  simple  command  is a sequence of arguments interspersed with I/O redirections.  If the
       first argument is the name of an rc function or of one of rc's built-in  commands,  it  is
       executed  by  rc.  Otherwise if the name starts with a slash (/), it must be the path name
       of the program to be executed.  Names containing no initial slash are searched  for  in  a
       list  of  directory  names  stored  in $path.  The first executable file of the given name
       found in a directory in $path is the program to be executed.  To be executable,  the  user
       must  have  execute  permission  (see  stat(3))  and the file must be either an executable
       binary for the current machine's CPU type, or a shell script.  Shell scripts begin with  a
       line containing the full path name of a shell (usually /bin/rc), prefixed by

       The  first  word  of a simple command cannot be a keyword unless it is quoted or otherwise
       disguised.  The keywords are
            for in while if not switch fn ~ ! @

   Arguments and Variables
       A number of constructions may be used where rc's syntax requires an  argument  to  appear.
       In  many  cases  a  construction's  value will be a list of arguments rather than a single
       string.

       The simplest kind of argument is the unquoted word: a sequence of one or  more  characters
       none of which is a blank, tab, newline, or any of the following:
            # ; & | ^ $ = ` ' { } ( ) < >
       An  unquoted  word  that  contains  any of the characters * ?  [ is a pattern for matching
       against file names.  The character * matches any sequence of characters,  ?   matches  any
       single  character, and [class] matches any character in the class.  If the first character
       of class is ~, the class is complemented.  The class may also contain pairs of  characters
       separated  by  -,  standing for all characters lexically between the two.  The character /
       must appear explicitly in a pattern,  as  must  the  first  character  of  the  path  name
       components  .   and  ...   A pattern is replaced by a list of arguments, one for each path
       name matched, except that a pattern matching no names is not replaced by the  empty  list,
       but rather stands for itself.  Pattern matching is done after all other operations.  Thus,
            x=/tmp echo $x^/*.c
       matches /tmp/*.c, rather than matching /*.c and then prefixing /tmp.

       A quoted word is a sequence of characters surrounded by single quotes (').  A single quote
       is represented in a quoted word by a pair of quotes ('').

       Each of the following is an argument.
       (arguments)
              The value of a sequence of arguments enclosed in parentheses is a  list  comprising
              the  members  of  each  element  of the sequence.  Argument lists have no recursive
              structure, although their syntax  may  suggest  it.   The  following  are  entirely
              equivalent:
                   echo hi there everybody
                   ((echo) (hi there) everybody)
       $argument
       $argument(subscript)
              The  argument  after  the  $  is the name of a variable whose value is substituted.
              Multiple levels of indirection are possible, but of questionable utility.  Variable
              values  are  lists  of  strings.   If  argument is a number n, the value is the nth
              element of $*, unless $* doesn't have n elements, in which case the value is empty.
              If  argument  is  followed  by  a  parenthesized  list  of  subscripts,  the  value
              substituted is  a  list  composed  of  the  requested  elements  (origin  1).   The
              parenthesis must follow the variable name with no spaces.  Subscripts can also take
              the form m-n or m- to indicate a sequence of elements.   Assignments  to  variables
              are described below.
       $#argument
              The  value  is  the  number  of  elements  in the named variable.  A variable never
              assigned a value has zero elements.
       $"argument
              The value is a single string  containing  the  components  of  the  named  variable
              separated by spaces.  A variable with zero elements yields the empty string.
       `{command}
              rc  executes the command and reads its standard output, splitting it into a list of
              arguments, using characters in $ifs as separators.  If $ifs is not  otherwise  set,
              its value is ' \t\n'.
       <{command}
       >{command}
              The  command  is executed asynchronously with its standard output or standard input
              connected to a pipe.  The value of the argument is the name of a file referring  to
              the  other  end of the pipe.  This allows the construction of non-linear pipelines.
              For example, the following runs two commands old and new and uses  cmp  to  compare
              their outputs
                   cmp <{old} <{new}
       argument^argument
              The  ^  operator  concatenates its two operands.  If the two operands have the same
              number of components, they are concatenated pairwise.  If  not,  then  one  operand
              must  have  one  component,  and  the other must be non-empty, and concatenation is
              distributive.

   Free Carets
       In most circumstances, rc will insert the ^ operator automatically between words that  are
       not  separated by white space.  Whenever one of $ ' ` follows a quoted or unquoted word or
       an unquoted word follows a quoted word with no intervening blanks or tabs, a ^ is inserted
       between  the  two.   If  an unquoted word immediately follows a $ and contains a character
       other than an alphanumeric, underscore, or *, a  ^  is  inserted  before  the  first  such
       character.  Thus

              cc -$flags $stem.c

       is equivalent to

              cc -^$flags $stem^.c

   I/O Redirections
       The  sequence  >file  redirects  the standard output file (file descriptor 1, normally the
       terminal) to the named file; >>file appends standard output to  the  file.   The  standard
       input  file  (file descriptor 0, also normally the terminal) may be redirected from a file
       by the sequence <file, or from an inline `here document'  by  the  sequence  <<eof-marker.
       The  contents  of a here document are lines of text taken from the command input stream up
       to a line containing nothing but the eof-marker, which may be either a quoted or  unquoted
       word.   If  eof-marker  is  unquoted,  variable  names of the form $word have their values
       substituted from rc's environment.  If $word is followed by a  caret  (^),  the  caret  is
       deleted.  If eof-marker is quoted, no substitution occurs.

       Redirections  may  be  applied to a file-descriptor other than standard input or output by
       qualifying the redirection operator with a number in square brackets.   For  example,  the
       diagnostic output (file descriptor 2) may be redirected by writing cc junk.c >[2]junk.

       A file descriptor may be redirected to an already open descriptor by writing >[fd0=fd1] or
       <[fd0=fd1].  Fd1 is a previously opened file descriptor and fd0 becomes a new copy (in the
       sense of dup(3)) of it.  A file descriptor may be closed by writing >[fd0=] or <[fd0=].

       Redirections  are executed from left to right.  Therefore, cc junk.c >/dev/null >[2=1] and
       cc junk.c >[2=1] >/dev/null have different effects: the  first  puts  standard  output  in
       /dev/null  and  then  puts  diagnostic  output in the same place, where the second directs
       diagnostic output to the terminal and sends standard output to /dev/null.

   Compound Commands
       A pair of commands separated by a pipe operator (|) is a command.  The standard output  of
       the  left  command is sent through a pipe to the standard input of the right command.  The
       pipe operator may be decorated to use different  file  descriptors.   |[fd]  connects  the
       output end of the pipe to file descriptor fd rather than 1.  |[fd0=fd1] connects output to
       fd1 of the left command and input to fd0 of the right command.

       A pair of commands separated by && or || is a command.  In either case, the  left  command
       is  executed  and  its  exit  status examined.  If the operator is && the right command is
       executed if the left command's status is null.  || causes the right command to be executed
       if the left command's status is non-null.

       The exit status of a command may be inverted (non-null is changed to null, null is changed
       to non-null) by preceding it with a !.

       The | operator has highest precedence, and is left-associative (i.e. binds tighter to  the
       left  than  the  right).   !   has  intermediate precedence, and && and || have the lowest
       precedence.

       The unary @ operator, with precedence equal to !, causes its operand to be executed  in  a
       subshell.

       Each of the following is a command.
       if ( list ) command
              A  list  is  a sequence of commands, separated by &, ;, or newline.  It is executed
              and if its exit status is null, the command is executed.
       if not command
              The immediately  preceding  command  must  have  been  if(list)  command.   If  its
              condition was non-zero, the command is executed.
       for(name in arguments) command
       for(name) command
              The command is executed once for each argument with that argument assigned to name.
              If the argument list is omitted, $* is used.
       while(list) command
              The list is executed repeatedly until its exit status is non-null.   Each  time  it
              returns  null status, the command is executed.  An empty list is taken to give null
              status.
       switch(argument){list}
              The list is searched for simple commands beginning with the word case.  (The search
              is  only  at  the `top level' of the list.  That is, cases in nested constructs are
              not found.)  Argument is  matched  against  each  word  following  case  using  the
              pattern-matching  algorithm described above, except that / and the first characters
              of .  and ..  need not be matched explicitly.  When a match is found,  commands  in
              the  list  are executed up to the next following case command (at the top level) or
              the closing brace.
       {list}
              Braces serve to alter the grouping of commands implied by operator priorities.  The
              body is a sequence of commands separated by &, ;, or newline.
       fn name{list}
       fn name
              The  first  form  defines a function with the given name.  Subsequently, whenever a
              command whose first argument is name is  encountered,  the  current  value  of  the
              remainder  of  the command's argument list will be assigned to $*, after saving its
              current value, and rc will execute  the  list.   The  second  form  removes  name's
              function definition.
       fn note{list}
       fn note
              A  function  with  a  special  name will be called when rc receives a corresponding
              note; see notify(3).  The valid note names (and  corresponding  notes)  are  sighup
              (hangup),  sigint  (interrupt),  sigalrm (alarm), and sigfpe (floating point trap).
              By default rc exits on receiving any signal,  except  when  run  interactively,  in
              which  case  interrupts and quits normally cause rc to stop whatever it's doing and
              start reading a new command.  The second form causes rc to handle a signal  in  the
              default manner.  Rc recognizes an artificial note, sigexit, which occurs when rc is
              about to finish executing.
       name=argument command
              Any command may  be  preceded  by  a  sequence  of  assignments  interspersed  with
              redirections.   The  assignments  remain  in  effect  until the end of the command,
              unless the command is empty (i.e. the assignments stand alone), in which case  they
              are effective until rescinded by later assignments.

   Built-in Commands
       These  commands  are executed internally by rc, usually because their execution changes or
       depends on rc's internal state.
       . file ...
              Execute commands from file.  $* is set for the duration to  the  remainder  of  the
              argument list following file.  File is searched for using $path.
       builtin command ...
              Execute command as usual except that any function named command is ignored in favor
              of the built-in meaning.
       cd [dir]
              Change the current directory to dir.   The  default  argument  is  $home.   dir  is
              searched for in each of the directories mentioned in $cdpath.
       eval [arg ...]
              The  arguments  are  concatenated separated by spaces into a single string, read as
              input to rc, and executed.
       exec [command ...]
              This instance of rc replaces itself with the given (non-built-in) command.
       flag f [+-]
              Either set (+), clear (-), or test (neither + nor -) the  flag  f,  where  f  is  a
              single character, one of the command line flags (see Invocation, below).
       exit [status]
              Exit with the given exit status.  If none is given, the current value of $status is
              used.
       rfork [nNeEsfFm]
              Become a new process group using  rfork(flags)  where  flags  is  composed  of  the
              bitwise OR of the rfork flags specified by the option letters (see fork(2)).  If no
              flags are given, they default to ens.  The flags  and  their  meanings  are:  n  is
              RFNAMEG;  N  is RFCNAMEG; e is RFENVG; E is RFCENVG; s is RFNOTEG; f is RFFDG; F is
              RFCFDG; and m is RFNOMNT.
       shift [n]
              Delete the first n (default 1) elements of $*.
       wait [pid]
              Wait for the process with the  given  pid  to  exit.   If  no  pid  is  given,  all
              outstanding processes are waited for.
       whatis name ...
              Print  the value of each name in a form suitable for input to rc.  The output is an
              assignment to any variable, the definition of any function, a call to  builtin  for
              any built-in command, or the completed pathname of any executable file.
       ~ subject pattern ...
              The  subject  is  matched  against  each  pattern  in  sequence.  If it matches any
              pattern, $status is set to zero.  Otherwise, $status is set to one.   Patterns  are
              the same as for file name matching, except that / and the first character of .  and
              ..  need not be matched explicitly.  The patterns are not subjected  to  file  name
              matching  before  the  ~  command  is  executed,  so  they  need not be enclosed in
              quotation marks.

   Environment
       The environment is a list of strings made available to executing binaries by  the  kernel.
       Rc  creates  an environment entry for each variable whose value is non-empty, and for each
       function.  The string for a variable entry has the variable's name followed by =  and  its
       value.   If  the  value  has  more  than  one  component, these are separated by SOH (001)
       characters.  The string for a function is just the rc input  that  defines  the  function.
       The name of a function in the environment is the function name preceded by

       When rc starts executing it reads variable and function definitions from its environment.

   Special Variables
       The following variables are set or used by rc.
       $*       Set  to  rc's  argument  list  during initialization.  Whenever a .  command or a
                function is executed, the current value is saved and $* receives the new argument
                list.  The saved value is restored on completion of the .  or function.
       $apid    Whenever  a process is started asynchronously with &, $apid is set to its process
                id.
       $home    The default directory for cd.
       $ifs     The input field separators used in backquote substitutions.  If $ifs is  not  set
                in rc's environment, it is initialized to blank, tab and newline.
       $path    The search path used to find commands and input files for the .  command.  If not
                set in the environment, it is initialized by parsing the $PATH  variable  (as  in
                sh(1))  or  by  path=(. /bin).   The  variables  $path  and  $PATH are maintained
                together: changes to one will be reflected in the other.
       $pid     Set during initialization to rc's process id.
       $prompt  When rc is run interactively, the first component of $prompt  is  printed  before
                reading  each  command.   The  second  component is printed whenever a newline is
                typed and more lines are required to complete the command.  If  not  set  in  the
                environment, it is initialized by prompt=('% ' ' ').
       $status  Set  to  the wait message of the last-executed program.  (unless started with &).
                !  and ~ also change $status.  Its value is used to control execution in &&,  ||,
                if and while commands.  When rc exits at end-of-file of its input or on executing
                an exit command with no argument, $status is its exit status.

   Invocation
       If rc is started with no arguments it reads commands from standard input.   Otherwise  its
       first  non-flag  argument  is  the  name of a file from which to read commands (but see -c
       below).  Subsequent arguments become the initial value of $*.  Rc  accepts  the  following
       command-line flags.
       -c string  Commands are read from string.
       -s         Print out exit status after any command where the status is non-null.
       -e         Exit if $status is non-null after executing a simple command.
       -i         If  -i  is  present,  or  rc  is given no arguments and its standard input is a
                  terminal, it runs interactively.  Commands are prompted for using $prompt.
       -I         Makes sure rc is not run interactively.
       -l         If -l is given or the first character of argument zero is -, rc reads  commands
                  from $home/lib/profile, if it exists, before reading its normal input.
       -p         A no-op.
       -d         A no-op.
       -v         Echo input on file descriptor 2 as it is read.
       -x         Print each simple command before executing it.
       -r         Print debugging information (internal form of commands as they are executed).

SOURCE

       /src/cmd/rc

SEE ALSO

       Tom Duff, ``Rc - The Plan 9 Shell''.

BUGS

       There  should  be  a  way  to  match  patterns against whole lists rather than just single
       strings.

       Using ~ to check the value of $status changes $status.

       Functions that use here documents don't work.

       Free carets don't get inserted next to keywords.

       The <{command} syntax  depends  on  the  underlying  operating  system  providing  a  file
       descriptor device tree at /dev/fd.

       By default, FreeBSD 5 does not provide file descriptors greater than 2 in /dev/fd.  To fix
       this, add

              /fdescfs    /dev/fd    fdescfs    rw    0    0

       to /etc/fstab, and then mount /dev/fd.  (Adding the line to fstab ensures  causes  FreeBSD
       to mount the file system automatically at boot time.)

                                                                                       RC(1plan9)