Provided by: 9base_6-14_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)