rc.1 - 9base - revived minimalist port of Plan 9 userland to Unix
(HTM) git clone git://git.suckless.org/9base
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
rc.1 (20154B)
---
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 (3));
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 (3))
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 Subscripts can also take the form
212 .IB m - n
213 or
214 .IB m -
215 to indicate a sequence of elements.
216 Assignments to variables are described below.
217 .HP
218 .BI $# argument
219 .br
220 The value is the number of elements in the named variable.
221 A variable
222 never assigned a value has zero elements.
223 .HP
224 $"\c
225 .I argument
226 .br
227 The value is a single string containing the components of the named variable
228 separated by spaces. A variable with zero elements yields the empty string.
229 .HP
230 .BI `{ command }
231 .br
232 .I rc
233 executes the
234 .I command
235 and reads its standard output, splitting it into a list of arguments,
236 using characters in
237 .B $ifs
238 as separators.
239 If
240 .B $ifs
241 is not otherwise set, its value is
242 .BR "'\ \et\en'" .
243 .HP
244 .BI <{ command }
245 .HP
246 .BI >{ command }
247 .br
248 The
249 .I command
250 is executed asynchronously with its standard output or standard input
251 connected to a pipe.
252 The value of the argument is the name of a file
253 referring to the other end of the pipe.
254 This allows the construction of
255 non-linear pipelines.
256 For example, the following runs two commands
257 .B old
258 and
259 .B new
260 and uses
261 .B cmp
262 to compare their outputs
263 .EX
264 cmp <{old} <{new}
265 .EE
266 .HP
267 .IB argument ^ argument
268 .br
269 The
270 .B ^
271 operator concatenates its two operands.
272 If the two operands
273 have the same number of components, they are concatenated pairwise.
274 If not,
275 then one operand must have one component, and the other must be non-empty,
276 and concatenation is distributive.
277 .PD
278 .SS Free Carets
279 In most circumstances,
280 .I rc
281 will insert the
282 .B ^
283 operator automatically between words that are not separated by white space.
284 Whenever one of
285 .B $
286 .B '
287 .B `
288 follows a quoted or unquoted word or an unquoted word follows a quoted word
289 with no intervening blanks or tabs,
290 a
291 .B ^
292 is inserted between the two.
293 If an unquoted word immediately follows a
294 .BR $
295 and contains a character other than an alphanumeric, underscore,
296 or
297 .BR * ,
298 a
299 .B ^
300 is inserted before the first such character.
301 Thus
302 .IP
303 .B cc -$flags $stem.c
304 .LP
305 is equivalent to
306 .IP
307 .B cc -^$flags $stem^.c
308 .SS I/O Redirections
309 The sequence
310 .BI > file
311 redirects the standard output file (file descriptor 1, normally the
312 terminal) to the named
313 .IR file ;
314 .BI >> file
315 appends standard output to the file.
316 The standard input file (file descriptor 0, also normally the terminal)
317 may be redirected from a file by the sequence
318 .BI < file \f1,
319 or from an inline `here document'
320 by the sequence
321 .BI << eof-marker\f1.
322 The contents of a here document are lines of text taken from the command
323 input stream up to a line containing nothing but the
324 .IR eof-marker ,
325 which may be either a quoted or unquoted word.
326 If
327 .I eof-marker
328 is unquoted, variable names of the form
329 .BI $ word
330 have their values substituted from
331 .I rc's
332 environment.
333 If
334 .BI $ word
335 is followed by a caret
336 .RB ( ^ ),
337 the caret is deleted.
338 If
339 .I eof-marker
340 is quoted, no substitution occurs.
341 .PP
342 Redirections may be applied to a file-descriptor other than standard input
343 or output by qualifying the redirection operator
344 with a number in square brackets.
345 For example, the diagnostic output (file descriptor 2)
346 may be redirected by writing
347 .BR "cc junk.c >[2]junk" .
348 .PP
349 A file descriptor may be redirected to an already open descriptor by writing
350 .BI >[ fd0 = fd1 ]
351 or
352 .BI <[ fd0 = fd1 ]\f1.
353 .I Fd1
354 is a previously opened file descriptor and
355 .I fd0
356 becomes a new copy (in the sense of
357 .IR dup (3))
358 of it.
359 A file descriptor may be closed by writing
360 .BI >[ fd0 =]
361 or
362 .BI <[ fd0 =]\f1.
363 .PP
364 Redirections are executed from left to right.
365 Therefore,
366 .B cc junk.c >/dev/null >[2=1]
367 and
368 .B cc junk.c >[2=1] >/dev/null
369 have different effects: the first puts standard output in
370 .BR /dev/null
371 and then puts diagnostic output in the same place, where the second
372 directs diagnostic output to the terminal and sends standard output to
373 .BR /dev/null .
374 .SS Compound Commands
375 A pair of commands separated by a pipe operator
376 .RB ( | )
377 is a command.
378 The standard output of the left command is sent through a pipe
379 to the standard input of the right command.
380 The pipe operator may be decorated
381 to use different file descriptors.
382 .BI |[ fd ]
383 connects the output end of the pipe to file descriptor
384 .I fd
385 rather than 1.
386 .BI |[ fd0 = fd1 ]
387 connects output to
388 .I fd1
389 of the left command and input to
390 .I fd0
391 of the right command.
392 .PP
393 A pair of commands separated by
394 .B &&
395 or
396 .B ||
397 is a command.
398 In either case, the left command is executed and its exit status examined.
399 If the operator is
400 .B &&
401 the right command is executed if the left command's status is null.
402 .B ||
403 causes the right command to be executed if the left command's status is non-null.
404 .PP
405 The exit status of a command may be inverted (non-null is changed to null, null
406 is changed to non-null) by preceding it with a
407 .BR ! .
408 .PP
409 The
410 .B |
411 operator has highest precedence, and is left-associative (i.e. binds tighter
412 to the left than the right).
413 .B !
414 has intermediate precedence, and
415 .B &&
416 and
417 .B ||
418 have the lowest precedence.
419 .PP
420 The unary
421 .B @
422 operator, with precedence equal to
423 .BR ! ,
424 causes its operand to be executed in a subshell.
425 .PP
426 Each of the following is a command.
427 .PD 0
428 .HP
429 .B if (
430 .I list
431 .B )
432 .I command
433 .br
434 A
435 .I list
436 is a sequence of commands, separated by
437 .BR & ,
438 .BR ; ,
439 or newline.
440 It is executed and
441 if its exit status is null, the
442 .I command
443 is executed.
444 .HP
445 .B if not
446 .I command
447 .br
448 The immediately preceding command must have been
449 .BI if( list )
450 .IR command .
451 If its condition was non-zero, the
452 .I command
453 is executed.
454 .HP
455 .BI for( name
456 .B in
457 .IB arguments )
458 .I command
459 .HP
460 .BI for( name )
461 .I command
462 .br
463 The
464 .I command
465 is executed once for each
466 .IR argument
467 with that argument assigned to
468 .IR name .
469 If the argument list is omitted,
470 .B $*
471 is used.
472 .HP
473 .BI while( list )
474 .I command
475 .br
476 The
477 .I list
478 is executed repeatedly until its exit status is non-null.
479 Each time it returns null status, the
480 .I command
481 is executed.
482 An empty
483 .I list
484 is taken to give null status.
485 .HP
486 .BI "switch(" argument "){" list }
487 .br
488 The
489 .IR list
490 is searched for simple commands beginning with the word
491 .BR case .
492 (The search is only at the `top level' of the
493 .IR list .
494 That is,
495 .B cases
496 in nested constructs are not found.)
497 .I Argument
498 is matched against each word following
499 .B case
500 using the pattern-matching algorithm described above, except that
501 .B /
502 and the first characters of
503 .B .
504 and
505 .B ..
506 need not be matched explicitly.
507 When a match is found, commands in the list are executed up to the next
508 following
509 .B case
510 command (at the top level) or the closing brace.
511 .HP
512 .BI { list }
513 .br
514 Braces serve to alter the grouping of commands implied by operator
515 priorities.
516 The
517 .I body
518 is a sequence of commands separated by
519 .BR & ,
520 .BR ; ,
521 or newline.
522 .HP
523 .BI "fn " name { list }
524 .HP
525 .BI "fn " name
526 .br
527 The first form defines a function with the given
528 .IR name .
529 Subsequently, whenever a command whose first argument is
530 .I name
531 is encountered, the current value of
532 the remainder of the command's argument list will be assigned to
533 .BR $* ,
534 after saving its current value, and
535 .I rc
536 will execute the
537 .IR list .
538 The second form removes
539 .IR name 's
540 function definition.
541 .HP
542 .BI "fn " note { list }
543 .br
544 .HP
545 .BI "fn " note
546 .br
547 A function with a special name will be called when
548 .I rc
549 receives a corresponding note; see
550 .IR notify (3).
551 The valid note names (and corresponding notes) are
552 .B sighup
553 .RB ( hangup ),
554 .B sigint
555 .RB ( interrupt ),
556 .BR sigalrm
557 .RB ( alarm ),
558 and
559 .B sigfpe
560 (floating point trap).
561 By default
562 .I rc
563 exits on receiving any signal, except when run interactively,
564 in which case interrupts and quits normally cause
565 .I rc
566 to stop whatever it's doing and start reading a new command.
567 The second form causes
568 .I rc
569 to handle a signal in the default manner.
570 .I Rc
571 recognizes an artificial note,
572 .BR sigexit ,
573 which occurs when
574 .I rc
575 is about to finish executing.
576 .HP
577 .IB name = "argument command"
578 .br
579 Any command may be preceded by a sequence of assignments
580 interspersed with redirections.
581 The assignments remain in effect until the end of the command, unless
582 the command is empty (i.e. the assignments stand alone), in which case
583 they are effective until rescinded by later assignments.
584 .PD
585 .SS Built-in Commands
586 These commands are executed internally by
587 .IR rc ,
588 usually because their execution changes or depends on
589 .IR rc 's
590 internal state.
591 .PD 0
592 .HP
593 .BI . " file ..."
594 .br
595 Execute commands from
596 .IR file .
597 .B $*
598 is set for the duration to the remainder of the argument list following
599 .IR file .
600 .I File
601 is searched for using
602 .BR $path .
603 .HP
604 .BI builtin " command ..."
605 .br
606 Execute
607 .I command
608 as usual except that any function named
609 .I command
610 is ignored in favor of the built-in meaning.
611 .HP
612 .BI "cd [" dir "]"
613 .br
614 Change the current directory to
615 .IR dir .
616 The default argument is
617 .BR $home .
618 .I dir
619 is searched for in each of the directories mentioned in
620 .BR $cdpath .
621 .HP
622 .BI "eval [" "arg ..." "]"
623 .br
624 The arguments are concatenated separated by spaces into a single string,
625 read as input to
626 .IR rc ,
627 and executed.
628 .HP
629 .BI "exec [" "command ..." "]"
630 .br
631 This instance of
632 .I rc
633 replaces itself with the given (non-built-in)
634 .IR command .
635 .HP
636 .BI "flag " f " [+-]"
637 .br
638 Either set
639 .RB ( + ),
640 clear
641 .RB ( - ),
642 or test (neither
643 .B +
644 nor
645 .BR - )
646 the flag
647 .IR f ,
648 where
649 .I f
650 is a single character, one of the command line flags (see Invocation, below).
651 .HP
652 .BI "exit [" status "]"
653 .br
654 Exit with the given exit status.
655 If none is given, the current value of
656 .B $status
657 is used.
658 .HP
659 .BR "rfork " [ nNeEsfFm ]
660 .br
661 Become a new process group using
662 .BI rfork( flags )
663 where
664 .I flags
665 is composed of the bitwise OR of the
666 .B rfork
667 flags specified by the option letters
668 (see
669 .IR fork (2)).
670 If no
671 .I flags
672 are given, they default to
673 .BR ens .
674 The
675 .I flags
676 and their meanings are:
677 .B n
678 is
679 .BR RFNAMEG ;
680 .B N
681 is
682 .BR RFCNAMEG ;
683 .B e
684 is
685 .BR RFENVG ;
686 .B E
687 is
688 .BR RFCENVG ;
689 .B s
690 is
691 .BR RFNOTEG ;
692 .B f
693 is
694 .BR RFFDG ;
695 .B F
696 is
697 .BR RFCFDG ;
698 and
699 .B m
700 is
701 .BR RFNOMNT .
702 .HP
703 .BI "shift [" n "]"
704 .br
705 Delete the first
706 .IR n
707 (default 1)
708 elements of
709 .BR $* .
710 .HP
711 .BI "wait [" pid "]"
712 .br
713 Wait for the process with the given
714 .I pid
715 to exit.
716 If no
717 .I pid
718 is given, all outstanding processes are waited for.
719 .HP
720 .BI whatis " name ..."
721 .br
722 Print the value of each
723 .I name
724 in a form suitable for input to
725 .IR rc .
726 The output is
727 an assignment to any variable,
728 the definition of any function,
729 a call to
730 .B builtin
731 for any built-in command, or
732 the completed pathname of any executable file.
733 .HP
734 .BI ~ " subject pattern ..."
735 .br
736 The
737 .I subject
738 is matched against each
739 .I pattern
740 in sequence.
741 If it matches any pattern,
742 .B $status
743 is set to zero.
744 Otherwise,
745 .B $status
746 is set to one.
747 Patterns are the same as for file name matching, except that
748 .B /
749 and the first character of
750 .B .
751 and
752 .B ..
753 need not be matched explicitly.
754 The
755 .I patterns
756 are not subjected to
757 file name matching before the
758 .B ~
759 command is executed, so they need not be enclosed in quotation marks.
760 .PD
761 .SS Environment
762 The
763 .I environment
764 is a list of strings made available to executing binaries by the
765 kernel.
766 .I Rc
767 creates an environment entry for each variable whose value is non-empty,
768 and for each function.
769 The string for a variable entry has the variable's name followed by
770 .B =
771 and its value.
772 If the value has more than one component, these
773 are separated by SOH (001)
774 characters.
775 The string for a function is just the
776 .I rc
777 input that defines the function.
778 The name of a function in the environment is the function name
779 preceded by
780 .LR fn# .
781 .PP
782 When
783 .I rc
784 starts executing it reads variable and function definitions from its
785 environment.
786 .SS Special Variables
787 The following variables are set or used by
788 .IR rc .
789 .PD 0
790 .TP \w'\fL$promptXX'u
791 .B $*
792 Set to
793 .IR rc 's
794 argument list during initialization.
795 Whenever a
796 .B .
797 command or a function is executed, the current value is saved and
798 .B $*
799 receives the new argument list.
800 The saved value is restored on completion of the
801 .B .
802 or function.
803 .TP
804 .B $apid
805 Whenever a process is started asynchronously with
806 .BR & ,
807 .B $apid
808 is set to its process id.
809 .TP
810 .B $home
811 The default directory for
812 .BR cd .
813 .TP
814 .B $ifs
815 The input field separators used in backquote substitutions.
816 If
817 .B $ifs
818 is not set in
819 .IR rc 's
820 environment, it is initialized to blank, tab and newline.
821 .TP
822 .B $path
823 The search path used to find commands and input files
824 for the
825 .B .
826 command.
827 If not set in the environment, it is initialized by
828 parsing the
829 .B $PATH
830 variable
831 (as in
832 .IR sh (1))
833 or by
834 .BR "path=(.\ /bin)" .
835 The variables
836 .B $path
837 and
838 .B $PATH
839 are maintained together: changes to one will be reflected in the other.
840 .\" Its use is discouraged; instead use
841 .\" .IR bind (1)
842 .\" to build a
843 .\" .B /bin
844 .\" containing what's needed.
845 .TP
846 .B $pid
847 Set during initialization to
848 .IR rc 's
849 process id.
850 .TP
851 .B $prompt
852 When
853 .I rc
854 is run interactively, the first component of
855 .B $prompt
856 is printed before reading each command.
857 The second component is printed whenever a newline is typed and more lines
858 are required to complete the command.
859 If not set in the environment, it is initialized by
860 .BR "prompt=('%\ '\ '\ ')" .
861 .TP
862 .B $status
863 Set to the wait message of the last-executed program.
864 (unless started with
865 .BR &).
866 .B !
867 and
868 .B ~
869 also change
870 .BR $status .
871 Its value is used to control execution in
872 .BR && ,
873 .BR || ,
874 .B if
875 and
876 .B while
877 commands.
878 When
879 .I rc
880 exits at end-of-file of its input or on executing an
881 .B exit
882 command with no argument,
883 .B $status
884 is its exit status.
885 .PD
886 .SS Invocation
887 If
888 .I rc
889 is started with no arguments it reads commands from standard input.
890 Otherwise its first non-flag argument is the name of a file from which
891 to read commands (but see
892 .B -c
893 below).
894 Subsequent arguments become the initial value of
895 .BR $* .
896 .I Rc
897 accepts the following command-line flags.
898 .PD 0
899 .TP \w'\fL-c\ \fIstring\fLXX'u
900 .BI -c " string"
901 Commands are read from
902 .IR string .
903 .TP
904 .B -s
905 Print out exit status after any command where the status is non-null.
906 .TP
907 .B -e
908 Exit if
909 .B $status
910 is non-null after executing a simple command.
911 .TP
912 .B -i
913 If
914 .B -i
915 is present, or
916 .I rc
917 is given no arguments and its standard input is a terminal,
918 it runs interactively.
919 Commands are prompted for using
920 .BR $prompt .
921 .TP
922 .B -I
923 Makes sure
924 .I rc
925 is not run interactively.
926 .TP
927 .B -l
928 If
929 .B -l
930 is given or the first character of argument zero is
931 .BR - ,
932 .I rc
933 reads commands from
934 .BR $home/lib/profile ,
935 if it exists, before reading its normal input.
936 .TP
937 .B -p
938 A no-op.
939 .TP
940 .B -d
941 A no-op.
942 .TP
943 .B -v
944 Echo input on file descriptor 2 as it is read.
945 .TP
946 .B -x
947 Print each simple command before executing it.
948 .TP
949 .B -r
950 Print debugging information (internal form of commands
951 as they are executed).
952 .PD
953 .SH SOURCE
954 .B \*9/src/cmd/rc
955 .SH "SEE ALSO"
956 Tom Duff,
957 ``Rc \- The Plan 9 Shell''.
958 .SH BUGS
959 There should be a way to match patterns against whole lists rather than
960 just single strings.
961 .PP
962 Using
963 .B ~
964 to check the value of
965 .B $status
966 changes
967 .BR $status .
968 .PP
969 Functions that use here documents don't work.
970 .PP
971 Free carets don't get inserted next to keywords.
972 .PP
973 The
974 .BI <{ command }
975 syntax depends on the underlying operating system
976 providing a file descriptor device tree at
977 .BR /dev/fd .
978 .PP
979 By default, FreeBSD 5
980 does not provide file descriptors greater than 2
981 in
982 .BR /dev/fd .
983 To fix this, add
984 .IP
985 .EX
986 /fdescfs /dev/fd fdescfs rw 0 0
987 .EE
988 .LP
989 to
990 .BR /etc/fstab ,
991 and then
992 .B mount
993 .BR /dev/fd .
994 (Adding the line to
995 .B fstab
996 ensures causes FreeBSD to mount the file system
997 automatically at boot time.)