TH RC 1
SH NAME
rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ \- command language
SH SYNOPSIS
B rc
[
B -srdiIlxepvV
]
[
B -c command
]
[
I file
[
I arg ...
]]
SH DESCRIPTION
I Rc
is the Plan 9 shell.
It executes command lines read from a terminal or a file or, with the
B -c
flag, from
I rc's
argument list.
SS Command Lines
A command line is a sequence of commands, separated by ampersands or semicolons
RB ( &
or
BR ; ),
terminated by a newline.
The commands are executed in sequence
from left to right.
I Rc
does not wait for a command followed by
B &
to finish executing before starting
the following command.
Whenever a command followed by
B &
is executed, its process id is assigned to the
I rc
variable
BR $apid .
Whenever a command
I not
followed by
B &
exits or is terminated, the
I rc
variable
B $status
gets the process's wait message (see
IR wait (2));
it will be the null string if the command was successful.
PP
A long command line may be continued on subsequent lines by typing
a backslash
RB ( \e )
followed by a newline.
This sequence is treated as though it were a blank.
Backslash is not otherwise a special character.
PP
A number-sign
RB ( # )
and any following characters up to (but not including) the next newline
are ignored, except in quotation marks.
SS Simple Commands
A simple command is a sequence of arguments interspersed with I/O redirections.
If the first argument is the name of an
I rc
function or of one of
I rc's
built-in commands, it is executed by
IR rc .
Otherwise if the name starts with a slash
RB ( / ),
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
BR $path .
The first executable file of the given name found
in a directory in
B $path
is the program to be executed.
To be executable, the user must have execute permission (see
IR stat (2))
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
BR /bin/rc ),
prefixed by
LR #! .
PP
The first word of a simple command cannot be a keyword unless it is
quoted or otherwise disguised.
The keywords are
EX
       for in while if not switch fn ~ ! @
EE
SS Arguments and Variables
A number of constructions may be used where
I 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.
PP
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:
EX
       # ; & | ^ $ = ` ' { } ( ) < >
EE
An unquoted word that contains any of the characters
B *
B ?
B [
is a pattern for matching against file names.
The character
B *
matches any sequence of characters,
B ?
matches any single character, and
BI [ class ]
matches any character in the
IR class .
If the first character of
I class
is
BR ~ ,
the class is complemented.
The
I class
may also contain pairs of characters separated by
BR - ,
standing for all characters lexically between the two.
The character
B /
must appear explicitly in a pattern, as must the
first character of the path name components
B .
and
BR .. .
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,
EX
       x=/tmp echo $x^/*.c
EE
matches
BR /tmp/*.c ,
rather than matching
B "/*.c
and then prefixing
BR /tmp .
PP
A quoted word is a sequence of characters surrounded by single quotes
RB ( ' ).
A single quote is represented in a quoted word by a pair of quotes
RB ( '' ).
PP
Each of the following is an argument.
PD 0
HP
BI ( arguments )
br
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:
EX
       echo hi there everybody
       ((echo) (hi there) everybody)
EE
HP
BI $ argument
HP
BI $ argument ( subscript )
br
The
I argument
after the
B $
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
I argument
is a number
IR n ,
the value is the
IR n th
element of
BR $* ,
unless
B $*
doesn't have
I n
elements, in which case the value is empty.
If
I 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.
HP
BI $# argument
br
The value is the number of elements in the named variable.
A variable
never assigned a value has zero elements.
HP
$"\c
I argument
br
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.
HP
BI `{ command }
br
I rc
executes the
I command
and reads its standard output, splitting it into a list of arguments,
using characters in
B $ifs
as separators.
If
B $ifs
is not otherwise set, its value is
BR "'\ \et\en'" .
HP
BI <{ command }
HP
BI >{ command }
br
The
I 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
B old
and
B new
and uses
B cmp
to compare their outputs
EX
       cmp <{old} <{new}
EE
HP
IB argument ^ argument
br
The
B ^
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.
PD
SS Free Carets
In most circumstances,
I rc
will insert the
B ^
operator automatically between words that are not separated by white space.
Whenever one of
B $
B '
B `
follows a quoted or unquoted word or an unquoted word follows a quoted word
with no intervening blanks or tabs,
a
B ^
is inserted between the two.
If an unquoted word immediately follows a
BR $
and contains a character other than an alphanumeric, underscore,
or
BR * ,
a
B ^
is inserted before the first such character.
Thus
IP
B cc -$flags $stem.c
LP
is equivalent to
IP
B cc -^$flags $stem^.c
SS I/O Redirections
The sequence
BI > file
redirects the standard output file (file descriptor 1, normally the
terminal) to the named
IR file ;
BI >> 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
BI < file \f1,
or from an inline `here document'
by the sequence
BI << eof-marker\f1.
The contents of a here document are lines of text taken from the command
input stream up to a line containing nothing but the
IR eof-marker ,
which may be either a quoted or unquoted word.
If
I eof-marker
is unquoted, variable names of the form
BI $ word
have their values substituted from
I rc's
environment.
If
BI $ word
is followed by a caret
RB ( ^ ),
the caret is deleted.
If
I eof-marker
is quoted, no substitution occurs.
PP
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
BR "cc junk.c >[2]junk" .
PP
A file descriptor may be redirected to an already open descriptor by writing
BI >[ fd0 = fd1 ]
or
BI <[ fd0 = fd1 ]\f1.
I Fd1
is a previously opened file descriptor and
I fd0
becomes a new copy (in the sense of
IR dup (2))
of it.
A file descriptor may be closed by writing
BI >[ fd0 =]
or
BI <[ fd0 =]\f1.
PP
Redirections are executed from left to right.
Therefore,
B cc junk.c >/dev/null >[2=1]
and
B cc junk.c >[2=1] >/dev/null
have different effects: the first puts standard output in
BR /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
BR /dev/null .
SS Compound Commands
A pair of commands separated by a pipe operator
RB ( | )
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.
BI |[ fd ]
connects the output end of the pipe to file descriptor
I fd
rather than 1.
BI |[ fd0 = fd1 ]
connects output to
I fd1
of the left command and input to
I fd0
of the right command.
PP
A pair of commands separated by
B &&
or
B ||
is a command.
In either case, the left command is executed and its exit status examined.
If the operator is
B &&
the right command is executed if the left command's status is null.
B ||
causes the right command to be executed if the left command's status is non-null.
PP
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
BR ! .
PP
The
B |
operator has highest precedence, and is left-associative (i.e. binds tighter
to the left than the right).
B !
has intermediate precedence, and
B &&
and
B ||
have the lowest precedence.
PP
The unary
B @
operator, with precedence equal to
BR ! ,
causes its operand to be executed in a subshell.
PP
Each of the following is a command.
PD 0
HP
B if (
I list
B )
I command
br
A
I list
is a sequence of commands, separated by
BR & ,
BR ; ,
or newline.
It is executed and
if its exit status is null, the
I command
is executed.
HP
B if not
I command
br
The immediately preceding command must have been
BI if( list )
IR command .
If its condition was non-zero, the
I command
is executed.
HP
BI for( name
B in
IB arguments )
I command
HP
BI for( name )
I command
br
The
I command
is executed once for each
IR argument
with that argument assigned to
IR name .
If the argument list is omitted,
B $*
is used.
HP
BI while( list )
I command
br
The
I list
is executed repeatedly until its exit status is non-null.
Each time it returns null status, the
I command
is executed.
An empty
I list
is taken to give null status.
HP
BI "switch(" argument "){" list }
br
The
IR list
is searched for simple commands beginning with the word
BR case .
(The search is only at the `top level' of the
IR list .
That is,
B cases
in nested constructs are not found.)
I Argument
is matched against each word following
B case
using the pattern-matching algorithm described above, except that
B /
and the first characters of
B .
and
B ..
need not be matched explicitly.
When a match is found, commands in the list are executed up to the next
following
B case
command (at the top level) or the closing brace.
HP
BI { list }
br
Braces serve to alter the grouping of commands implied by operator
priorities.
The
I body
is a sequence of commands separated by
BR & ,
BR ; ,
or newline.
HP
BI "fn " name { list }
HP
BI "fn " name
br
The first form defines a function with the given
IR name .
Subsequently, whenever a command whose first argument is
I name
is encountered, the current value of
the remainder of the command's argument list will be assigned to
BR $* ,
after saving its current value, and
I rc
will execute the
IR list .
The second form removes
IR name 's
function definition.
HP
BI "fn " note { list }
br
HP
BI "fn " note
br
A function with a special name will be called when
I rc
receives a corresponding note; see
IR notify (2).
The valid note names (and corresponding notes) are
B sighup
RB ( hangup ),
B sigint
RB ( interrupt ),
BR sigalrm
RB ( alarm ),
and
B sigfpe
(floating point trap).
By default
I rc
exits on receiving any signal, except when run interactively,
in which case interrupts and quits normally cause
I rc
to stop whatever it's doing and start reading a new command.
The second form causes
I rc
to handle a signal in the default manner.
I Rc
recognizes an artificial note,
BR sigexit ,
which occurs when
I rc
is about to finish executing.
HP
IB name = "argument command"
br
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.
PD
SS Built-in Commands
These commands are executed internally by
IR rc ,
usually because their execution changes or depends on
IR rc 's
internal state.
PD 0
HP
BI . " file ..."
br
Execute commands from
IR file .
B $*
is set for the duration to the remainder of the argument list following
IR file .
I File
is searched for using
BR $path .
HP
BI builtin " command ..."
br
Execute
I command
as usual except that any function named
I command
is ignored in favor of the built-in meaning.
HP
BI "cd [" dir "]"
br
Change the current directory to
IR dir .
The default argument is
BR $home .
I dir
is searched for in each of the directories mentioned in
BR $cdpath .
HP
BI "eval [" "arg ..." "]"
br
The arguments are concatenated separated by spaces into a single string,
read as input to
IR rc ,
and executed.
HP
BI "exec [" "command ..." "]"
br
This instance of
I rc
replaces itself with the given (non-built-in)
IR command .
HP
BI "flag " f " [+-]"
br
Either set
RB ( + ),
clear
RB ( - ),
or test (neither
B +
nor
BR - )
the flag
IR f ,
where
I f
is a single character, one of the command line flags (see Invocation, below).
HP
BI "exit [" status "]"
br
Exit with the given exit status.
If none is given, the current value of
B $status
is used.
HP
BR "rfork " [ nNeEsfFm ]
br
Become a new process group using
BI rfork( flags )
where
I flags
is composed of the bitwise OR of the
B rfork
flags specified by the option letters
(see
IR fork (2)).
If no
I flags
are given, they default to
BR ens .
The
I flags
and their meanings are:
B n
is
BR RFNAMEG ;
B N
is
BR RFCNAMEG ;
B e
is
BR RFENVG ;
B E
is
BR RFCENVG ;
B s
is
BR RFNOTEG ;
B f
is
BR RFFDG ;
B F
is
BR RFCFDG ;
and
B m
is
BR RFNOMNT .
HP
BI "shift [" n "]"
br
Delete the first
IR n
(default 1)
elements of
BR $* .
HP
BI "wait [" pid "]"
br
Wait for the process with the given
I pid
to exit.
If no
I pid
is given, all outstanding processes are waited for.
HP
BI whatis " name ..."
br
Print the value of each
I name
in a form suitable for input to
IR rc .
The output is
an assignment to any variable,
the definition of any function,
a call to
B builtin
for any built-in command, or
the completed pathname of any executable file.
HP
BI ~ " subject pattern ..."
br
The
I subject
is matched against each
I pattern
in sequence.
If it matches any pattern,
B $status
is set to zero.
Otherwise,
B $status
is set to one.
Patterns are the same as for file name matching, except that
B /
and the first character of
B .
and
B ..
need not be matched explicitly.
The
I patterns
are not subjected to
file name matching before the
B ~
command is executed, so they need not be enclosed in quotation marks.
PD
SS Environment
The
I environment
is a list of strings made available to executing binaries by the
B env
device
(see
IR env (3)).
I 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
B =
and its value.
If the value has more than one component, these
are separated by ctrl-a
RB ( '\e001' )
characters.
The string for a function is just the
I rc
input that defines the function.
The name of a function in the environment is the function name
preceded by
LR fn# .
PP
When
I rc
starts executing it reads variable and function definitions from its
environment.
SS Special Variables
The following variables are set or used by
IR rc .
PD 0
TP \w'\fL$promptXX'u
B $*
Set to
IR rc 's
argument list during initialization.
Whenever a
B .
command or a function is executed, the current value is saved and
B $*
receives the new argument list.
The saved value is restored on completion of the
B .
or function.
TP
B $apid
Whenever a process is started asynchronously with
BR & ,
B $apid
is set to its process id.
TP
B $home
The default directory for
BR cd .
TP
B $ifs
The input field separators used in backquote substitutions.
If
B $ifs
is not set in
IR rc 's
environment, it is initialized to blank, tab and newline.
TP
B $path
The search path used to find commands and input files
for the
B .
command.
If not set in the environment, it is initialized by
BR "path=(.\ /bin)" .
Its use is discouraged; instead use
IR bind (1)
to build a
B /bin
containing what's needed.
TP
B $pid
Set during initialization to
IR rc 's
process id.
TP
B $prompt
When
I rc
is run interactively, the first component of
B $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
BR "prompt=('%\ '\ '\ ')" .
TP
B $status
Set to the wait message of the last-executed program.
(unless started with
BR &).
B !
and
B ~
also change
BR $status .
Its value is used to control execution in
BR && ,
BR || ,
B if
and
B while
commands.
When
I rc
exits at end-of-file of its input or on executing an
B exit
command with no argument,
B $status
is its exit status.
PD
SS Invocation
If
I 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
B -c
below).
Subsequent arguments become the initial value of
BR $* .
I Rc
accepts the following command-line flags.
PD 0
TP \w'\fL-c\ \fIstring\fLXX'u
BI -c " string"
Commands are read from
IR string .
TP
B -s
Print out exit status after any command where the status is non-null.
TP
B -e
Exit if
B $status
is non-null after executing a simple command.
TP
B -i
If
B -i
is present, or
I rc
is given no arguments and its standard input is a terminal,
it runs interactively.
Commands are prompted for using
BR $prompt .
TP
B -I
Makes sure
I rc
is not run interactively.
TP
B -l
If
B -l
is given or the first character of argument zero is
BR - ,
I rc
reads commands from
BR $home/lib/profile ,
if it exists, before reading its normal input.
TP
B -p
A no-op.
TP
B -d
A no-op.
TP
B -v
Echo input on file descriptor 2 as it is read.
TP
B -x
Print each simple command before executing it.
TP
B -r
Print debugging information (internal form of commands
as they are executed).
PD
SH SOURCE
B /sys/src/cmd/rc
SH "SEE ALSO"
Tom Duff,
``Rc \- The Plan 9 Shell''.
SH BUGS
There should be a way to match patterns against whole lists rather than
just single strings.
br
Using
B ~
to check the value of
B $status
changes
BR $status .
br
Functions that use here documents don't work.
br
Free carets don't get inserted next to keywords.

You are viewing proxied material from sdf.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.