From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man1/rc.html | 655 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 655 insertions(+) create mode 100644 man/man1/rc.html (limited to 'man/man1/rc.html') diff --git a/man/man1/rc.html b/man/man1/rc.html new file mode 100644 index 00000000..a599adfd --- /dev/null +++ b/man/man1/rc.html @@ -0,0 +1,655 @@ + +rc(1) - Plan 9 from User Space + + + + +
+
+
RC(1)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 fn#. +
+ + 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
+ +
+ + /usr/local/plan9/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.)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3