1 .HTML "Rc — The Plan 9 Shell
2 . \" /*% refer -k -e -n -l3,2 -s < % | tbl | troff -ms | lp -dfn
3 .Tm shell programming language g
4 .de TP \" An indented paragraph describing some command, tagged with the command name
6 .if \\w'\\f(CW\\$1\\fR'-4n .br
10 \%\&\\$3\f(CW\\$1\fI\&\\$2\f\\n(Sf
13 Rc \(em The Plan 9 Shell
16 td@plan9.bell-labs.com
19 is a command interpreter for Plan 9 that
20 provides similar facilities to UNIX's
22 with some small additions and less idiosyncratic syntax.
23 This paper uses numerous examples to describe
25 features, and contrasts
27 with the Bourne shell, a model that many readers will be familiar with.
33 is similar in spirit but different in detail from UNIX's
34 Bourne shell. This paper describes
36 principal features with many small examples and a few larger ones.
37 It assumes familiarity with the Bourne shell.
43 has syntax familiar to Bourne-shell users.
44 All of the following behave as expected:
55 mk && v.out /*/bin/fb/*
56 rm -r junk || echo rm failed!
61 An argument that contains a space or one of
63 other syntax characters must be enclosed in apostrophes
68 An apostrophe in a quoted argument must be doubled:
70 echo 'How''s your father?'
75 An unquoted argument that contains any of the characters
79 is a pattern to be matched against file names.
82 character matches any sequence of characters,
84 matches any single character, and
86 matches any character in the
88 unless the first character of
92 in which case the class is complemented.
95 may also contain pairs of characters separated by
97 standing for all characters lexically between the two.
100 must appear explicitly in a pattern, as must the path name components
104 A pattern is replaced by a list of arguments, one for each path name matched,
105 except that a pattern matching no names is not replaced by the empty list;
106 rather it stands for itself.
110 UNIX's Bourne shell offers string-valued variables.
112 provides variables whose values are lists of arguments \(em
113 that is, arrays of strings. This is the principal difference
116 and traditional UNIX command interpreters.
117 Variables may be given values by typing, for example:
121 font=/lib/font/bit/pelm/ascii.9.font
123 The parentheses indicate that the value assigned to
125 is a list of two strings. The variables
129 are assigned lists containing a single string.
131 The value of a variable can be substituted into a command by
132 preceding its name with a
140 had been set as above, this would be equivalent to
144 Variables may be subscripted by numbers or lists of numbers,
150 These are equivalent to
155 There can be no space separating the variable's name from the
156 left parenthesis; otherwise, the subscript would be considered
157 a separate parenthesized list.
159 The number of strings in a variable can be determined by the
161 operator. For example,
165 would print 2 for this example.
167 The following two assignments are subtly different:
174 to a list containing no strings.
177 to a list containing a single string,
178 but the string contains no characters.
180 Although these may seem like more or less
181 the same thing (in Bourne's shell, they are
182 indistinguishable), they behave differently
183 in almost all circumstances.
194 All variables that have never been set have the value
197 Occasionally, it is convenient to treat a variable's value
198 as a single string. The elements of a string are concatenated
199 into a single string, with spaces between the elements, by
205 list=(How now brown cow)
216 cause the same output, viz:
230 has four members, but
232 has a single member, with three spaces separating its words.
238 is reading its input from a file, the file has access
239 to the arguments supplied on
241 command line. The variable
243 initially has the list of arguments assigned to it.
247 etc. are synonyms for
253 is the name of the file from which
260 has a string concatenation operator, the caret
262 to build arguments out of pieces.
266 is exactly equivalent to
272 contains the name of a command.
278 might compile the command's source code, leaving the
279 result in the appropriate file.
281 Concatenation distributes over lists. The following
290 cc main.c subr.c io.c
292 In detail, the rule is: if both operands of
294 are lists of the same non-zero number of strings, they are concatenated
295 pairwise. Otherwise, if one of the operands is a single string,
296 it is concatenated with each member of the other operand in turn.
297 Any other combination of operands is an error.
301 User demand has dictated that
303 insert carets in certain places, to make the syntax
304 look more like the Bourne shell. For example, this:
310 cc -^$flags $stems^.c
316 between two arguments that are not separated by white space.
317 Specifically, whenever one of
319 follows a quoted or unquoted word, or an unquoted word follows
320 a quoted word with no intervening blanks or tabs, an implicit
322 is inserted between the two. If an unquoted word immediately following a
324 contains a character other than an alphanumeric, underscore or
328 is inserted before the first such character.
332 It is often useful to build an argument list from the output of a command.
334 allows a command, enclosed in braces and preceded by a left quote,
336 anywhere that an argument is required. The command is executed and its
337 standard output captured.
338 The characters stored in the variable
340 are used to split the output into arguments.
343 cat `{ls -tr|sed 10q}
345 will concatenate the ten oldest files in the current directory in temporal order, given the
348 setting of space, tab, and newline.
352 The normal pipeline notation is general enough for almost all cases.
353 Very occasionally it is useful to have pipelines that are not linear.
354 Pipeline topologies more general than trees can require arbitrarily large pipe buffers,
355 or worse, can cause deadlock.
357 has syntax for some kinds of non-linear but treelike pipelines.
362 will regression-test a new version of a command.
366 followed by a command in braces causes the command to be run with
367 its standard output or input attached to a pipe. The parent command
370 is started with the other end of the pipe attached to some file descriptor
371 or other, and with an argument that will connect to the pipe when opened
374 Some commands are unprepared to deal with input files that turn out not to be seekable.
377 needs to read its input twice.
381 When a command exits it returns status to the program that executed it.
382 On Plan 9 status is a character string describing an error condition.
383 On normal termination it is empty.
386 captures command exit status in the variable
388 For a simple command the value of
390 is just as described above. For a pipeline
392 is set to the concatenation of the statuses of the pipeline components with
394 characters for separators.
397 has a several kinds of control flow,
398 many of them conditioned by the status returned from previously
399 executed commands. Any
412 A sequence of commands enclosed in
414 may be used anywhere a command is required.
417 {sleep 3600;echo 'Time''s up!'}&
419 will wait an hour in the background, then print a message.
422 sleep 3600;echo 'Time''s up!'&
424 would lock up the terminal for an hour,
425 then print the message in the background.
427 Control flow \(em \f(CWfor\fP
429 A command may be executed once for each member of a list
430 by typing, for example:
432 for(i in printf scanf putchar) look $i /usr/td/lib/dw.dat
434 This looks for each of the words
442 for(\fIname\fP in \fIlist\fP) \fIcommand\fP
446 for(\fIname\fP) \fIcommand\fP
450 is executed once for each member of
452 with that member assigned to variable
462 Conditional execution \(em \f(CWif\fP
465 also provides a general if-statement. For example:
467 for(i in *.c) if(cpp $i >/tmp/$i) vc /tmp/$i
469 runs the C compiler on each C source program that
470 cpp processes without error.
471 An `if not' statement provides a two-tailed conditional.
475 if(test -f /tmp/$i) echo $i already in /tmp
479 This loops over each file in
483 those that do not already appear there, and
484 printing a message for those that do.
486 Control flow \(em \f(CWwhile\fP
489 while statement looks like this:
491 while(newer subr.v subr.c) sleep 5
497 presumably because the C compiler finished with it.
499 If the controlling command is empty, the loop will not terminate.
508 Control flow \(em \f(CWswitch\fP
511 provides a switch statement to do pattern-matching on
512 arbitrary strings. Its general form is
515 case \fIpattern ...\fP
517 case \fIpattern ...\fP
523 attempts to match the word against the patterns in each case statement in turn.
524 Patterns are the same as for filename matching, except that
530 need not be matched explicitly.
532 If any pattern matches, the
533 commands following that case up to
534 the next case (or the end of the switch)
535 are executed, and execution of the switch
536 is complete. For example,
544 echo 'Usage: append [from] to'
547 is an append command. Called with one file argument,
548 it appends its standard input to the named file. With two, the
549 first is appended to the second. Any other number
550 elicits an error message.
554 command also matches patterns, and is often more concise than a switch.
555 Its arguments are a string and a list of patterns. It sets
557 to true if and only if any of the patterns matches the string.
558 The following example processes option arguments for the
563 while(~ $1 -* [1-9] 10){
582 Functions may be defined by typing
584 fn \fIname\fP { \fIcommands\fP }
586 Subsequently, whenever a command named
588 is encountered, the remainder of the command's
589 argument list will assigned to
597 will be restored on completion.
606 to look for occurrences of
608 in all program source files in the current directory.
610 Function definitions are deleted by writing
614 with no function body.
619 does one of several things to execute a simple command.
620 If the command name is the name of a function defined using
622 the function is executed.
623 Otherwise, if it is the name of a built-in command, the
624 built-in is executed directly by
626 Otherwise, directories mentioned in the variable
628 are searched until an executable file is found.
631 variable is discouraged in Plan 9. Instead, use the default
634 and bind what you need into
639 Several commands are executed internally by
641 because they are difficult to implement otherwise.
642 .TP ". [-i] \fIfile ...\f(CW
643 Execute commands from
646 is set for the duration to the reminder of the argument list following
649 is used to search for
653 indicates interactive input \(em a prompt
656 is printed before each command is read.
657 .TP "builtin \fIcommand ...\f(CW
660 as usual except that any function named
669 defines a replacement for the
671 built-in (see below) that announces the full name of the new directory.
672 .TP "cd [\fIdir\f(CW]
673 Change the current directory to
675 The default argument is
678 is a list of places in which to search for
680 .TP "eval [\fIarg ...\f(CW]
681 The arguments are concatenated (separated by spaces) into a string, read as input to
683 and executed. For example,
693 since the arguments of
699 after substituting for
701 .TP "exec [\fIcommand ...\f(CW]
703 replaces itself with the given
709 does not wait for the command to exit, and does not return to read any more commands.
710 .TP "exit [\fIstatus\f(CW]
712 exits immediately with the given status. If none is given, the current value of
715 .TP "flag \fIf\f(CW [+-]
716 This command manipulates and tests the command line flags (described below).
749 into a new process group with the following attributes:
756 n RFNAMEG Make a copy of the parent's name space
757 N RFCNAMEG Start with a new, empty name space
758 e RFENVG Make a copy of the parent's environment
759 E RFCENVG Start with a new, empty environment
760 s RFNOTEG Make a new note group
761 f RFFDG Make a copy of the parent's file descriptor space
762 F RFCFDG Make a new, empty file descriptor space
766 of the Programmer's Manual describes these attributes in more detail.
767 .TP "shift [\fIn\f(CW]
770 (default 1) elements of
772 .TP "wait [\fIpid\fP]
773 Wait for the process with the given
777 is given, all outstanding processes are waited for.
778 .TP "whatis \fIname ...\f(CW
779 Print the value of each
781 in a form suitable for input to
783 The output is an assignment to a variable, the definition of a function,
786 for a built-in command, or the path name of a binary program.
794 fn g {gre -e $1 *.[hycl]}
798 .TP "~ \fIsubject pattern ...\f(CW
801 is matched against each
806 Otherwise, it is set to
808 Patterns are the same as for filename matching.
811 are not subjected to filename replacement before the
813 command is executed, so they need not be enclosed in
814 quotation marks, unless of course, a literal match for
824 matches any single character, whereas
828 only matches a literal question mark.
830 Advanced I/O Redirection
833 allows redirection of file descriptors other than 0 and 1
834 (standard input and output) by specifying the file descriptor
843 vc junk.c >[2]junk.diag
845 saves the compiler's diagnostics from standard error in
848 File descriptors may be replaced by a copy, in the sense of
850 of an already-open file by typing, for example
854 This replaces file descriptor 2 with a copy of file descriptor 1.
855 It is more useful in conjunction with other redirections, like this
857 vc junk.c >junk.out >[2=1]
859 Redirections are evaluated from left to right, so this redirects
862 then points file descriptor 2 at the same file.
865 vc junk.c >[2=1] >junk.out
867 redirects file descriptor 2 to a copy of file descriptor 1
868 (presumably the terminal), and then directs file descriptor 1
869 to a file. In the first case, standard and diagnostic output
870 will be intermixed in
872 In the second, diagnostic output will appear on the terminal,
873 and standard output will be sent to the file.
875 File descriptors may be closed by using the duplication notation
876 with an empty right-hand side.
881 will discard diagnostics from the compilation.
883 Arbitrary file descriptors may be sent through
884 a pipe by typing, for example,
886 vc junk.c |[2] grep -v '^$'
888 This deletes blank lines
889 from the C compiler's error output. Note that the output
892 still appears on file descriptor 1.
894 Occasionally you may wish to connect the input side of
895 a pipe to some file descriptor other than zero.
900 creates a pipeline with
902 file descriptor 5 connected through a pipe to
909 procedures may include data, called ``here documents'',
910 to be provided as input to commands, as in this version of the
922 A here document is introduced by the redirection symbol
924 followed by an arbitrary EOF marker
926 in the example). Lines following the command,
927 up to a line containing only the EOF marker are saved
928 in a temporary file that is connected to the command's
929 standard input when it is run.
932 does variable substitution in here documents. The following command:
939 changes all occurrences of
947 in a here document, type
949 If the name of a variable is followed immediately by
951 the caret is deleted.
953 Variable substitution can be entirely suppressed by enclosing
954 the EOF marker following
956 in quotation marks, as in
959 Here documents may be provided on file descriptors other than 0 by typing, for example,
966 If a here document appears within a compound block, the contents of the document
967 must be after the whole block:
979 scripts normally terminate when an interrupt is received from the terminal.
980 A function with the name of a UNIX signal, in lower case, is defined in the usual way,
983 receives the corresponding note.
986 section of the Programmer's Manual discusses notes in some detail.
987 Notes of interest are:
989 The note was `hangup'.
990 Plan 9 sends this when the terminal has disconnected from
993 The note was `interrupt', usually sent when
994 the interrupt character (ASCII DEL) is typed on the terminal.
996 The note was `kill', normally sent by
999 An artificial note sent when
1010 sets a trap for the keyboard interrupt that
1011 removes a temporary file before exiting.
1013 Notes will be ignored if the note routine is set to
1015 Signals revert to their default behavior when their handlers'
1016 definitions are deleted.
1020 The environment is a list of name-value pairs made available to
1022 On Plan 9, the environment is stored in a file system named
1026 The value of each variable is stored in a separate file, with components
1027 terminated by zero bytes.
1029 maintained entirely in core, so no disk or network access is involved.)
1032 are shared on a per-process group basis \(mi when a new process group is
1033 created it effectively attaches
1035 to a new file system initialized with a copy of the old one.
1036 A consequence of this organization is that commands can change environment
1037 entries and see the changes reflected in
1040 Functions also appear in the environment, named by prefixing
1042 to their names, like
1047 It is often useful to set a variable for the duration
1048 of a single command. An assignment followed by a command
1049 has this effect. For example
1060 This works even for compound commands, like
1062 f=/fairly/long/file/name {
1063 { wc $f; spell $f; diff $f.old $f } |
1064 pr -h 'Facts about '$f | lp -dfn
1068 Examples \(em \fIcd, pwd\fP
1070 Here is a pair of functions that provide
1071 enhanced versions of the standard
1075 commands. (Thanks to Rob Pike for these.)
1077 ps1='% ' # default prompt
1078 tab=' ' # a tab character
1089 prompt=(`{basename `{pwd}}^$ps1 $tab)
1092 prompt=(`{basename `{pwd}}^$ps1 $tab)
1095 prompt=($1^$ps1 $tab)
1107 is a version of the standard
1109 that caches its value in variable
1113 can be quite slow to execute.
1114 (Recent versions of Plan 9 have very fast implementations of
1116 reducing the advantage of the
1124 built-in, and checks that it was successful.
1129 The prompt will include the last component of the
1130 current directory (except in the home directory,
1131 where it will be null), and
1133 will be reset either to the correct value or to
1137 function will work correctly.
1139 Examples \(em \fIman\fP
1143 command prints pages of the Programmer's Manual.
1144 It is called, for example, as
1150 In the first case, the page for
1152 in section 2 is printed.
1153 In the second case, the manual page for
1155 is printed. Since no manual section is specified,
1156 all sections are searched for the page, and it is found
1158 In the third case, the page for
1165 echo $0: No manual! >[1=2]
1168 NT=n # default nroff
1169 s='*' # section, default try all
1176 echo Usage: $0 '[-nt] [section] page ...' >[1=2]
1182 for(page in $pages){
1186 echo $0: $i not found >[1=2]
1192 to make a list of candidate manual pages.
1199 would not trigger filename matching
1200 \(em it's enclosed in quotation marks,
1201 and even if it weren't, it would be expanded
1204 Eval causes its arguments
1205 to be re-processed by
1207 parser and interpreter, effectively delaying
1210 until the assignment to
1213 Examples \(em \fIholmdel\fP
1217 script plays the deceptively simple game
1219 in which the players alternately name Bell Labs locations,
1220 the winner being the first to mention Holmdel.
1225 $1=`{awk '{print;exit}'}
1228 \&' # just a newline
1229 fn sigexit sigint sigquit sighup{
1261 while(read lab; ! grep -i -s $lab $t) echo No such location.
1262 if(~ $lab [hH]olmdel){
1270 This script is worth describing in detail
1271 (rather, it would be if it weren't so silly.)
1275 is an abbreviation for the name of a temporary file.
1281 in the names of temporary files insures that their
1282 names won't collide, in case more than one instance
1283 of the script is running at a time.
1287 argument is the name of a variable into which a
1288 line gathered from standard input is read.
1290 is set to just a newline. Thus
1292 input is not split apart at spaces, but the terminating
1295 A handler is set to catch
1302 signal. It just removes the temporary file and exits.
1304 The temporary file is initialized from a here
1305 document containing a list of Bell Labs locations, and
1306 the main loop starts.
1308 First, the program guesses a location (in
1312 program to pick a random line from the location list.
1313 It prints the location, and if it guessed Holmdel, prints
1314 a message and exits.
1318 function to get lines from standard input and validity-check
1319 them until it gets a legal name.
1320 Note that the condition part of a
1322 can be a compound command. Only the exit status of the
1323 last command in the sequence is checked.
1325 Again, if the result
1326 is Holmdel, it prints a message and exits.
1327 Otherwise it goes back to the top of the loop.
1332 draws heavily from Steve Bourne's
1334 Any successor of the Bourne shell is bound to
1335 suffer in comparison. I have tried to fix its
1336 best-acknowledged shortcomings and to simplify things
1337 wherever possible, usually by omitting inessential features.
1338 Only when irresistibly tempted have I introduced novel ideas.
1339 Obviously I have tinkered extensively with Bourne's syntax.
1341 The most important principle in
1343 design is that it's not a macro processor. Input is never
1344 scanned more than once by the lexical and syntactic analysis
1345 code (except, of course, by the
1349 is to break the rule).
1351 Bourne shell scripts can often be made
1352 to run wild by passing them arguments containing spaces.
1353 These will be split into multiple arguments using
1355 often at inopportune times.
1358 values of variables, including command line arguments, are not re-read
1359 when substituted into a command.
1360 Arguments have presumably been scanned in the parent process, and ought
1363 Why does Bourne re-scan commands after variable substitution?
1364 He needs to be able to store lists of arguments in variables whose values are
1366 If we eliminate re-scanning, we must change the type of variables, so that
1367 they can explicitly carry lists of strings.
1369 This introduces some
1370 conceptual complications. We need a notation for lists of words.
1371 There are two different kinds of concatenation, for strings \(em
1375 The difference between
1379 is confusing to novices,
1380 although the distinction is arguably sensible \(em
1381 a null argument is not the same as no argument.
1383 Bourne also rescans input when doing command substitution.
1384 This is because the text enclosed in back-quotes is not
1385 a string, but a command. Properly, it ought to
1386 be parsed when the enclosing command is, but this makes
1388 handle nested command substitutions, like this:
1390 size=`wc -l \e`ls -t|sed 1q\e``
1392 The inner back-quotes must be escaped
1393 to avoid terminating the outer command.
1394 This can get much worse than the above example;
1397 required is exponential in the nesting depth.
1399 fixes this by making the backquote a unary operator
1400 whose argument is a command, like this:
1402 size=`{wc -l `{ls -t|sed 1q}}
1404 No escapes are ever required, and the whole thing
1405 is parsed in one pass.
1409 defines signal handlers as though they were functions,
1410 instead of associating a string with each signal, as Bourne does,
1411 with the attendant possibility of getting a syntax error message
1412 in response to typing the interrupt character. Since
1414 parses input when typed, it reports errors when you make them.
1416 For all this trouble, we gain substantial semantic simplifications.
1417 There is no need for the distinction between
1421 There is no need for four types of quotation, nor the
1422 extremely complicated rules that govern them. In
1424 you use quotation marks when you want a syntax character
1425 to appear in an argument, or an argument that is the empty string,
1426 and at no other time.
1428 is no longer used, except in the one case where it was indispensable:
1429 converting command output into argument lists during command substitution.
1431 This also avoids an important UNIX security hole.
1438 to execute a command. It is impossible to use either
1439 of these routines with any assurance that the specified command will
1440 be executed, even if the caller of
1444 specifies a full path name for the command. This can be devastating
1445 if it occurs in a set-userid program.
1448 is used to split the command into words, so an attacker can just
1451 in his environment and leave a Trojan horse
1456 in the current working directory before running the privileged program.
1458 fixes this by never rescanning input for any reason.
1460 Most of the other differences between
1462 and the Bourne shell are not so serious. I eliminated Bourne's
1463 peculiar forms of variable substitution, like
1465 echo ${a=b} ${c-d} ${e?error}
1467 because they are little used, redundant and easily
1468 expressed in less abstruse terms.
1469 I deleted the builtins
1480 because they seem redundant or
1481 only marginally useful.
1483 Where Bourne's syntax draws from Algol 68,
1485 is based on C or Awk. This is harder to defend.
1486 I believe that, for example
1488 if(test -f junk) rm junk
1490 is better syntax than
1492 if test -f junk; then rm junk; fi
1494 because it is less cluttered with keywords,
1495 it avoids the semicolons that Bourne requires
1497 and the syntax characters better set off the
1498 active parts of the command.
1500 The one bit of large-scale syntax that Bourne
1501 unquestionably does better than
1512 bracket. As a result, the parser cannot
1513 tell whether or not to expect an
1515 clause without looking ahead in its input.
1516 The problem is that after reading, for example
1518 if(test -f junk) echo junk found
1520 in interactive mode,
1522 cannot decide whether to execute it immediately and print
1529 In the Bourne shell, this is not a problem, because the
1531 command must end with
1533 regardless of whether it contains an
1538 admittedly feeble solution is to declare that the
1540 clause is a separate statement, with the semantic
1541 proviso that it must immediately follow an
1547 as a reminder that something odd is going on.
1548 The only noticeable consequence of this is that
1549 the braces are required in the construction
1552 if(test -f $i) echo $i found
1553 if not echo $i not found
1558 resolves the ``dangling else'' ambiguity in opposition
1559 to most people's expectations.
1561 It is remarkable that in the four most recent editions of the UNIX system
1562 programmer's manual the Bourne shell grammar described in the manual page
1563 does not admit the command
1565 This is surely an oversight, but it suggests something darker:
1566 nobody really knows what the Bourne shell's grammar is. Even examination
1567 of the source code is little help. The parser is implemented by recursive
1568 descent, but the routines corresponding to the syntactic categories all
1569 have a flag argument that subtly changes their operation depending on the
1572 parser is implemented using
1574 so I can say precisely what the grammar is.
1578 Rob Pike, Howard Trickey and other Plan 9 users have been insistent, incessant
1579 sources of good ideas and criticism. Some examples in this document are plagiarized
1588 UNIX Time-Sharing System: The UNIX Shell,
1589 Bell System Technical Journal, Volume 57 number 6, July-August 1978
projects / plan9front.git / blob