9base-rc

RC(1)                       General Commands Manual                      RC(1)



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