123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997 |
- .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
- .I command
- ]
- [
- .B -m
- .I initial
- ]
- [
- .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.
- Subscripts can also take the form
- .IB m - n
- or
- .IB m -
- to indicate a sequence of elements.
- 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 }
- .HP
- .BI ` "split " { 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'" .
- In the second form of the command, split is used instead of
- .BR $ifs .
- .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.
- The standard input file
- may also be redirected from a file by the sequence
- .BI <> file \f1,
- which opens
- .I file
- exactly once, for reading and writing.
- .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 ],
- .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 .
- .PP
- .B newconn <>/net/tcp/clone >[1=0]
- opens
- .B /net/tcp/clone
- exactly once for reading and writing and puts it on standard input and output.
- .B lpd <>[3]/net/tcp/42/data
- opens
- .B /net/tcp/42/data
- exactly once for reading and writing and puts it on file descriptor 3.
- .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 -m
- Read commands to initialize
- .I rc
- from
- .I initial
- instead of from
- .BR /rc/lib/rcmain .
- .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.
- .PP
- Using
- .B ~
- to check the value of
- .B $status
- changes
- .BR $status .
- .PP
- Functions containing here documents don't work.
- .PP
- Free carets don't get inserted next to keywords.
|