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