![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to rc CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Plan 9 NeXT] / lucent / sys / man / 1|
Return to rc CVS log | Up to [Plan 9 NeXT] / lucent / sys / man / 1 |
1.1 root 1: .TH RC 1
2: .SH NAME
3: rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ \- command language
4: .SH SYNOPSIS
5: .B rc
6: [
7: .B -srdiIlxepvV
8: ]
9: [
10: .B -c command
11: ]
12: [
13: .I file
14: [
15: .I arg ...
16: ]
17: .SH DESCRIPTION
18: .I Rc
19: is the Plan 9 shell.
20: It executes command lines read from a terminal or a file or, with the
21: .B -c
22: flag, from
23: .I rc's
24: argument list.
25: .SS Command Lines
26: A command line is a sequence of commands, separated by ampersands or semicolons
27: .RB ( &
28: or
29: .BR ; ),
30: terminated by a newline.
31: The commands are executed in sequence
32: from left to right.
33: .I Rc
34: does not wait for a command followed by
35: .B &
36: to finish executing before starting
37: the following command.
38: Whenever a command followed by
39: .B &
40: is executed, its process id is assigned to the
41: .I rc
42: variable
43: .BR $apid .
44: Whenever a command
45: .I not
46: followed by
47: .B &
48: exits or is terminated, the
49: .I rc
50: variable
51: .B $status
52: gets the process's wait message (see
53: .IR wait (2));
54: it will be the null string if the command was successful.
55: .PP
56: A long command line may be continued on subsequent lines by typing
57: a backslash
58: .RB ( \e )
59: followed by a newline.
60: This sequence is treated as though it were a blank.
61: Backslash is not otherwise a special character.
62: .PP
63: A number-sign
64: .RB ( # )
65: and any following characters up to (but not including) the next newline
66: are ignored, except in quotation marks.
67: .SS Simple Commands
68: A simple command is a sequence of arguments interspersed with I/O redirections.
69: If the first argument is the name of an
70: .I rc
71: function or of one of
72: .I rc's
73: built-in commands, it is executed by
74: .IR rc .
75: Otherwise if the name starts with a slash
76: .RB ( / ),
77: it must be the path name of the program to be executed.
78: Names containing no initial slash are searched for in
79: a list of directory names stored in
80: .BR $path .
81: The first executable file of the given name found
82: in a directory in
83: .B $path
84: is the program to be executed.
85: To be executable, the user must have execute permission (see
86: .IR stat (2))
87: and the file must be either an executable binary
88: for the current machine's CPU type, or a shell script.
89: Shell scripts begin with a line containing the full path name of a shell
90: (usually
91: .BR /bin/rc ),
92: prefixed by
93: .LR #! .
94: .PP
95: The first word of a simple command cannot be a keyword unless it is
96: quoted or otherwise disguised.
97: The keywords are
98: .EX
99: for in while if not switch fn ~ ! @
100: .EE
101: .SS Arguments and Variables
102: A number of constructions may be used where
103: .I rc's
104: syntax requires an argument to appear.
105: In many cases a construction's
106: value will be a list of arguments rather than a single string.
107: .PP
108: The simplest kind of argument is the unquoted word:
109: a sequence of one or more characters none of which is a blank, tab,
110: newline, or any of the following:
111: .EX
112: # ; & | ^ $ = ` ' { } ( ) < >
113: .EE
114: An unquoted word that contains any of the characters
115: .B *
116: .B ?
117: .B [
118: is a pattern for matching against file names.
119: The character
120: .B *
121: matches any sequence of characters,
122: .B ?
123: matches any single character, and
124: .BI [ class ]
125: matches any character in the
126: .IR class .
127: If the first character of
128: .I class
129: is
130: .BR ~ ,
131: the class is complemented.
132: The
133: .I class
134: may also contain pairs of characters separated by
135: .BR - ,
136: standing for all characters lexically between the two.
137: The character
138: .B /
139: must appear explicitly in a pattern, as must the
140: first character of the path name components
141: .B .
142: and
143: .BR .. .
144: A pattern is replaced by a list of arguments, one for each path name matched,
145: except that a pattern matching no names is not replaced by the empty list,
146: but rather stands for itself.
147: Pattern matching is done after all other
148: operations.
149: Thus,
150: .EX
151: x=/tmp echo $x^/*.c
152: .EE
153: matches
154: .BR /tmp/*.c ,
155: rather than matching
156: .B "/*.c
157: and then prefixing
158: .BR /tmp .
159: .PP
160: A quoted word is a sequence of characters surrounded by single quotes
161: .RB ( ' ).
162: A single quote is represented in a quoted word by a pair of quotes
163: .RB ( '' ).
164: .PP
165: Each of the following is an argument.
166: .PD 0
167: .HP
168: .BI ( arguments )
169: .br
170: The value of a sequence of arguments enclosed in parentheses is
171: a list comprising the members of each element of the sequence.
172: Argument lists have no recursive structure, although their syntax may
173: suggest it.
174: The following are entirely equivalent:
175: .EX
176: echo hi there everybody
177: ((echo) (hi there) everybody)
178: .EE
179: .HP
180: .BI $ argument
181: .HP
182: .BI $ argument ( subscript )
183: .br
184: The
185: .I argument
186: after the
187: .B $
188: is the name of a variable whose value is substituted.
189: Multiple levels
190: of indirection are possible, but of questionable utility.
191: Variable values
192: are lists of strings.
193: If
194: .I argument
195: is a number
196: .IR n ,
197: the value is the
198: .IR n th
199: element of
200: .BR $* ,
201: unless
202: .B $*
203: doesn't have
204: .I n
205: elements, in which case the value is empty.
206: If
207: .I argument
208: is followed by a parenthesized list of subscripts, the
209: value substituted is a list composed of the requested elements (origin 1).
210: The parenthesis must follow the variable name with no spaces.
211: Assignments to variables are described below.
212: .HP
213: .BI $# argument
214: .br
215: The value is the number of elements in the named variable.
216: A variable
217: never assigned a value has zero elements.
218: .HP
219: $"\c
220: .I argument
221: .br
222: The value is a single string containing the components of the named variable
223: separated by spaces. A variable with zero elements yields the empty string.
224: .HP
225: .BI `{ command }
226: .br
227: .I rc
228: executes the
229: .I command
230: and reads its standard output, splitting it into a list of arguments,
231: using characters in
232: .B $ifs
233: as separators.
234: If
235: .B $ifs
236: is not otherwise set, its value is
237: .BR "'\ \et\en'" .
238: .HP
239: .BI <{ command }
240: .HP
241: .BI >{ command }
242: .br
243: The
244: .I command
245: is executed asynchronously with its standard output or standard input
246: connected to a pipe.
247: The value of the argument is the name of a file
248: referring to the other end of the pipe.
249: This allows the construction of
250: non-linear pipelines.
251: For example, the following runs two commands
252: .B old
253: and
254: .B new
255: and uses
256: .B cmp
257: to compare their outputs
258: .EX
259: cmp <{old} <{new}
260: .EE
261: .HP
262: .IB argument ^ argument
263: .br
264: The
265: .B ^
266: operator concatenates its two operands.
267: If the two operands
268: have the same number of components, they are concatenated pairwise.
269: If not,
270: then one operand must have one component, and the other must be non-empty,
271: and concatenation is distributive.
272: .PD
273: .SS Free Carets
274: In most circumstances,
275: .I rc
276: will insert the
277: .B ^
278: operator automatically between words that are not separated by white space.
279: Whenever one of
280: .B $
281: .B '
282: .B `
283: follows a quoted or unquoted word or an unquoted word follows a quoted word
284: with no intervening blanks or tabs,
285: a
286: .B ^
287: is inserted between the two.
288: If an unquoted word immediately follows a
289: .BR $
290: and contains a character other than an alphanumeric, underscore,
291: or
292: .BR * ,
293: a
294: .B ^
295: is inserted before the first such character.
296: Thus
297: .IP
298: .B cc -$flags $stem.c
299: .LP
300: is equivalent to
301: .IP
302: .B cc -^$flags $stem^.c
303: .SS I/O Redirections
304: The sequence
305: .BI > file
306: redirects the standard output file (file descriptor 1, normally the
307: terminal) to the named
308: .IR file ;
309: .BI >> file
310: appends standard output to the file.
311: The standard input file (file descriptor 0, also normally the terminal)
312: may be redirected from a file by the sequence
313: .BI < file \f1,
314: or from an inline `here document'
315: by the sequence
316: .BI << eof-marker\f1.
317: The contents of a here document are lines of text taken from the command
318: input stream up to a line containing nothing but the
319: .IR eof-marker ,
320: which may be either a quoted or unquoted word.
321: If
322: .I eof-marker
323: is unquoted, variable names of the form
324: .BI $ word
325: have their values substituted from
326: .I rc's
327: environment.
328: If
329: .BI $ word
330: is followed by a caret
331: .RB ( ^ ),
332: the caret is deleted.
333: If
334: .I eof-marker
335: is quoted, no substitution occurs.
336: .PP
337: Redirections may be applied to a file-descriptor other than standard input
338: or output by qualifying the redirection operator
339: with a number in square brackets.
340: For example, the diagnostic output (file descriptor 2)
341: may be redirected by writing
342: .BR "cc junk.c >[2]junk" .
343: .PP
344: A file descriptor may be redirected to an already open descriptor by writing
345: .BI >[ fd0 = fd1 ]
346: or
347: .BI <[ fd0 = fd1 ]\f1.
348: .I Fd1
349: is a previously opened file descriptor and
350: .I fd0
351: becomes a new copy (in the sense of
352: .IR dup (2))
353: of it.
354: A file descriptor may be closed by writing
355: .BI >[ fd0 =]
356: or
357: .BI <[ fd0 =]\f1.
358: .PP
359: Redirections are executed from left to right.
360: Therefore,
361: .B cc junk.c >/dev/null >[2=1]
362: and
363: .B cc junk.c >[2=1] >/dev/null
364: have different effects: the first puts standard output in
365: .BR /dev/null
366: and then puts diagnostic output in the same place, where the second
367: directs diagnostic output to the terminal and sends standard output to
368: .BR /dev/null .
369: .SS Compound Commands
370: A pair of commands separated by a pipe operator
371: .RB ( | )
372: is a command.
373: The standard output of the left command is sent through a pipe
374: to the standard input of the right command.
375: The pipe operator may be decorated
376: to use different file descriptors.
377: .BI |[ fd ]
378: connects the output end of the pipe to file descriptor
379: .I fd
380: rather than 1.
381: .BI |[ fd0 = fd1 ]
382: connects output to
383: .I fd1
384: of the left command and input to
385: .I fd0
386: of the right command.
387: .PP
388: A pair of commands separated by
389: .B &&
390: or
391: .B ||
392: is a command.
393: In either case, the left command is executed and its exit status examined.
394: If the operator is
395: .B &&
396: the right command is executed if the left command's status is null.
397: .B ||
398: causes the right command to be executed if the left command's status is non-null.
399: .PP
400: The exit status of a command may be inverted (non-null is changed to null, null
401: is changed to non-null) by preceding it with a
402: .BR ! .
403: .PP
404: The
405: .B |
406: operator has highest precedence, and is left-associative (i.e. binds tighter
407: to the left than the right).
408: .B !
409: has intermediate precedence, and
410: .B &&
411: and
412: .B ||
413: have the lowest precedence.
414: .PP
415: The unary
416: .B @
417: operator, with precedence equal to
418: .BR ! ,
419: causes its operand to be executed in a subshell.
420: .PP
421: Each of the following is a command.
422: .PD 0
423: .HP
424: .B if (
425: .I list
426: .B )
427: .I command
428: .br
429: A
430: .I list
431: is a sequence of commands, separated by
432: .BR & ,
433: .BR ; ,
434: or newline.
435: It is executed and
436: if its exit status is null, the
437: .I command
438: is executed.
439: .HP
440: .B if not
441: .I command
442: .br
443: The immediately preceding command must have been
444: .BI if( list )
445: .IR command .
446: If its condition was non-zero, the
447: .I command
448: is executed.
449: .HP
450: .BI for( name
451: .B in
452: .IB arguments )
453: .I command
454: .HP
455: .BI for( name )
456: .I command
457: .br
458: The
459: .I command
460: is executed once for each
461: .IR argument
462: with that argument assigned to
463: .IR name .
464: If the argument list is omitted,
465: .B $*
466: is used.
467: .HP
468: .BI while( list )
469: .I command
470: .br
471: The
472: .I list
473: is executed repeatedly until its exit status is non-null.
474: Each time it returns null status, the
475: .I command
476: is executed.
477: An empty
478: .I list
479: is taken to give null status.
480: .HP
481: .BI "switch(" argument "){" list }
482: .br
483: The
484: .IR list
485: is searched for simple commands beginning with the word
486: .BR case .
487: (The search is only at the `top level' of the
488: .IR list .
489: That is,
490: .B cases
491: in nested constructs are not found.)
492: .I Argument
493: is matched against each word following
494: .B case
495: using the pattern-matching algorithm described above, except that
496: .B /
497: and the first characters of
498: .B .
499: and
500: .B ..
501: need not be matched explicitly.
502: When a match is found, commands in the list are executed up to the next
503: following
504: .B case
505: command (at the top level) or the closing brace.
506: .HP
507: .BI { list }
508: .br
509: Braces serve to alter the grouping of commands implied by operator
510: priorities.
511: The
512: .I body
513: is a sequence of commands separated by
514: .BR & ,
515: .BR ; ,
516: or newline.
517: .HP
518: .BI "fn " name { list }
519: .HP
520: .BI "fn " name
521: .br
522: The first form defines a function with the given
523: .IR name .
524: Subsequently, whenever a command whose first argument is
525: .I name
526: is encountered, the current value of
527: the remainder of the command's argument list will be assigned to
528: .BR $* ,
529: after saving its current value, and
530: .I rc
531: will execute the
532: .IR list .
533: The second form removes
534: .IR name 's
535: function definition.
536: .HP
537: .BI "fn " note { list }
538: .br
539: .HP
540: .BI "fn " note
541: .br
542: A function with a special name will be called when
543: .I rc
544: receives a corresponding note; see
545: .IR notify (2).
546: The valid note names (and corresponding notes) are
547: .B sighup
548: .RB ( hangup ),
549: .B sigint
550: .RB ( interrupt ),
551: .BR sigalrm
552: .RB ( alarm ),
553: and
554: .B sigfpe
555: (floating point trap).
556: By default
557: .I rc
558: exits on receiving any signal, except when run interactively,
559: in which case interrupts and quits normally cause
560: .I rc
561: to stop whatever it's doing and start reading a new command.
562: The second form causes
563: .I rc
564: to handle a signal in the default manner.
565: .I Rc
566: recognizes an artificial note,
567: .BR sigexit ,
568: which occurs when
569: .I rc
570: is about to finish executing.
571: .HP
572: .IB name = "argument command"
573: .br
574: Any command may be preceded by a sequence of assignments
575: interspersed with redirections.
576: The assignments remain in effect until the end of the command, unless
577: the command is empty (i.e. the assignments stand alone), in which case
578: they are effective until rescinded by later assignments.
579: .PD
580: .SS Built-in Commands
581: These commands are executed internally by
582: .IR rc ,
583: usually because their execution changes or depends on
584: .IR rc 's
585: internal state.
586: .PD 0
587: .HP
588: .BI . " file ..."
589: .br
590: Execute commands from
591: .IR file .
592: .B $*
593: is set for the duration to the remainder of the argument list following
594: .IR file .
595: .I File
596: is searched for using
597: .BR $path .
598: .HP
599: .BI builtin " command ..."
600: .br
601: Execute
602: .I command
603: as usual except that any function named
604: .I command
605: is ignored in favor of the built-in meaning.
606: .HP
607: .BI "cd [" dir "]"
608: .br
609: Change the current directory to
610: .IR dir .
611: The default argument is
612: .BR $home .
613: .I dir
614: is searched for in each of the directories mentioned in
615: .BR $cdpath .
616: .HP
617: .BI "eval [" "arg ..." "]"
618: .br
619: The arguments are concatenated separated by spaces into a single string,
620: read as input to
621: .IR rc ,
622: and executed.
623: .HP
624: .BI "exec [" "command ..." "]"
625: .br
626: This instance of
627: .I rc
628: replaces itself with the given (non-built-in)
629: .IR command .
630: .HP
631: .BI "flag " f " [+-]"
632: .br
633: Either set
634: .RB ( + ),
635: clear
636: .RB ( - ),
637: or test (neither
638: .B +
639: nor
640: .BR - )
641: the flag
642: .IR f ,
643: where
644: .I f
645: is a single character, one of the command line flags (see Invocation, below).
646: .HP
647: .BI "exit [" status "]"
648: .br
649: Exit with the given exit status.
650: If none is given, the current value of
651: .B $status
652: is used.
653: .HP
654: .BR "rfork " [ nNeEsfF ]
655: .br
656: Become a new process group using
657: .BI rfork( flags )
658: where
659: .I flags
660: is composed of the bitwise OR of the
661: .B rfork
662: flags specified by the option letters
663: (see
664: .IR fork (2)).
665: If no
666: .I flags
667: are given, they default to
668: .BR ens .
669: The
670: .I flags
671: and their meanings are:
672: .B n
673: is
674: .BR RFNAMEG ;
675: .B N
676: is
677: .BR RFCNAMEG ;
678: .B e
679: is
680: .BR RFENVG ;
681: .B E
682: is
683: .BR RFCENVG ;
684: .B s
685: is
686: .BR RFNOTEG ;
687: .B f
688: is
689: .BR RFFDG ;
690: and
691: .B F
692: is
693: .BR RFCFDG .
694: .HP
695: .BI "shift [" n "]"
696: .br
697: Delete the first
698: .IR n
699: (default 1)
700: elements of
701: .BR $* .
702: .HP
703: .BI "wait [" pid "]"
704: .br
705: Wait for the process with the given
706: .I pid
707: to exit.
708: If no
709: .I pid
710: is given, all outstanding processes are waited for.
711: .HP
712: .BI whatis " name ..."
713: .br
714: Print the value of each
715: .I name
716: in a form suitable for input to
717: .IR rc .
718: The output is
719: an assignment to any variable,
720: the definition of any function,
721: a call to
722: .B builtin
723: for any built-in command, or
724: the completed pathname of any executable file.
725: .HP
726: .BI ~ " subject pattern ..."
727: .br
728: The
729: .I subject
730: is matched against each
731: .I pattern
732: in sequence.
733: If it matches any pattern,
734: .B $status
735: is set to zero.
736: Otherwise,
737: .B $status
738: is set to one.
739: Patterns are the same as for file name matching, except that
740: .B /
741: and the first character of
742: .B .
743: and
744: .B ..
745: need not be matched explicitly.
746: The
747: .I patterns
748: are not subjected to
749: file name matching before the
750: .B ~
751: command is executed, so they need not be enclosed in quotation marks.
752: .PD
753: .SS Environment
754: The
755: .I environment
756: is a list of strings made available to executing binaries by the
757: .B env
758: device
759: (see
760: .IR env (3)).
761: .I Rc
762: creates an environment entry for each variable whose value is non-empty,
763: and for each function.
764: The string for a variable entry has the variable's name followed by
765: .B =
766: and its value.
767: If the value has more than one component, these
768: are separated by ctrl-a
769: .RB ( '\e001' )
770: characters.
771: The string for a function is just the
772: .I rc
773: input that defines the function.
774: The name of a function in the environment is the function name
775: preceded by
776: .LR fn# .
777: .PP
778: When
779: .I rc
780: starts executing it reads variable and function definitions from its
781: environment.
782: .SS Special Variables
783: The following variables are set or used by
784: .IR rc .
785: .PD 0
786: .TP \w'\fL$promptXX'u
787: .B $*
788: Set to
789: .IR rc 's
790: argument list during initialization.
791: Whenever a
792: .B .
793: command or a function is executed, the current value is saved and
794: .B $*
795: receives the new argument list.
796: The saved value is restored on completion of the
797: .B .
798: or function.
799: .TP
800: .B $apid
801: Whenever a process is started asynchronously with
802: .BR & ,
803: .B $apid
804: is set to its process id.
805: .TP
806: .B $home
807: The default directory for
808: .BR cd .
809: .TP
810: .B $ifs
811: The input field separators used in backquote substitutions.
812: If
813: .B $ifs
814: is not set in
815: .IR rc 's
816: environment, it is initialized to blank, tab and newline.
817: .TP
818: .B $path
819: The search path used to find commands and input files
820: for the
821: .B .
822: command.
823: If not set in the environment, it is initialized by
824: .BR "path=(.\ /bin)" .
825: Its use is discouraged; instead use
826: .IR bind (1)
827: to build a
828: .B /bin
829: containing what's needed.
830: .TP
831: .B $pid
832: Set during initialization to
833: .IR rc 's
834: process id.
835: .TP
836: .B $prompt
837: When
838: .I rc
839: is run interactively, the first component of
840: .B $prompt
841: is printed before reading each command.
842: The second component is printed whenever a newline is typed and more lines
843: are required to complete the command.
844: If not set in the environment, it is initialized by
845: .BR "prompt=('%\ '\ '\ ')" .
846: .TP
847: .B $status
848: Set to the wait message of the last-executed program.
849: (unless started with
850: .BR &).
851: .B !
852: and
853: .B ~
854: also change
855: .BR $status .
856: Its value is used to control execution in
857: .BR && ,
858: .BR || ,
859: .B if
860: and
861: .B while
862: commands.
863: When
864: .I rc
865: exits at end-of-file of its input or on executing an
866: .B exit
867: command with no argument,
868: .B $status
869: is its exit status.
870: .PD
871: .SS Invocation
872: If
873: .I rc
874: is started with no arguments it reads commands from standard input.
875: Otherwise its first non-flag argument is the name of a file from which
876: to read commands (but see
877: .B -c
878: below).
879: Subsequent arguments become the initial value of
880: .BR $* .
881: .I Rc
882: accepts the following command-line flags.
883: .PD 0
884: .TP \w'\fL-c\ \fIstring\fLXX'u
885: .BI -c " string"
886: Commands are read from
887: .IR string .
888: .TP
889: .B -s
890: Print out exit status after any command where the status is non-null.
891: .TP
892: .B -e
893: Exit if
894: .B $status
895: is non-null after executing a simple command.
896: .TP
897: .B -i
898: If
899: .B -i
900: is present, or
901: .I rc
902: is given no arguments and its standard input is a terminal,
903: it runs interactively.
904: Commands are prompted for using
905: .BR $prompt .
906: .TP
907: .B -I
908: Makes sure
909: .I rc
910: is not run interactively.
911: .TP
912: .B -l
913: If
914: .B -l
915: is given or the first character of argument zero is
916: .BR - ,
917: .I rc
918: reads commands from
919: .BR $home/lib/profile ,
920: if it exists, before reading its normal input.
921: .TP
922: .B -p
923: A no-op.
924: .TP
925: .B -d
926: A no-op.
927: .TP
928: .B -v
929: Echo input on file descriptor 2 as it is read.
930: .TP
931: .B -x
932: Print each simple command before executing it.
933: .TP
934: .B -r
935: Print debugging information (internal form of commands
936: as they are executed).
937: .PD
938: .SH SOURCE
939: .B /sys/src/cmd/rc
940: .SH "SEE ALSO"
941: Tom Duff,
942: ``Rc \- The Plan 9 Shell''.
943: .SH BUGS
944: There should be a way to match patterns against whole lists rather than
945: just single strings.
946: .br
947: Using
948: .B ~
949: to check the value of
950: .B $status
951: changes
952: .BR $status .
953: .br
954: Functions that use here documents don't work.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.