rc.1 (20266B)
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 .MR 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 .MR 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 .BI <>{ command } 268 .br 269 The 270 .I command 271 is executed asynchronously with its standard input and 272 output each connected to a pipe. The value of the argument 273 is a pair of file names referring to the two other ends 274 of the pipes, in the order corresponding to the symbols 275 .B < 276 and 277 .B > 278 (first the pipe connected to the command's standard output, 279 then the pipe connected to its standard input). 280 .HP 281 .IB argument ^ argument 282 .br 283 The 284 .B ^ 285 operator concatenates its two operands. 286 If the two operands 287 have the same number of components, they are concatenated pairwise. 288 If not, 289 then one operand must have one component, and the other must be non-empty, 290 and concatenation is distributive. 291 .PD 292 .SS Free Carets 293 .I Rc 294 will insert the 295 .B ^ 296 operator automatically between words that are not separated by white space. 297 Thus 298 .IP 299 .B cc -$flags $stem.c 300 .LP 301 is equivalent to 302 .IP 303 .B cc -^$flags $stem^.c 304 .SS I/O Redirections 305 The sequence 306 .BI > file 307 redirects the standard output file (file descriptor 1, normally the 308 terminal) to the named 309 .IR file ; 310 .BI >> file 311 appends standard output to the file. 312 The standard input file (file descriptor 0, also normally the terminal) 313 may be redirected from a file by the sequence 314 .BI < file \f1, 315 or from an inline `here document' 316 by the sequence 317 .BI << eof-marker\f1. 318 The contents of a here document are lines of text taken from the command 319 input stream up to a line containing nothing but the 320 .IR eof-marker , 321 which may be either a quoted or unquoted word. 322 If 323 .I eof-marker 324 is unquoted, variable names of the form 325 .BI $ word 326 have their values substituted from 327 .I rc's 328 environment. 329 If 330 .BI $ word 331 is followed by a caret 332 .RB ( ^ ), 333 the caret is deleted. 334 If 335 .I eof-marker 336 is quoted, no substitution occurs. 337 .PP 338 Redirections may be applied to a file-descriptor other than standard input 339 or output by qualifying the redirection operator 340 with a number in square brackets. 341 For example, the diagnostic output (file descriptor 2) 342 may be redirected by writing 343 .BR "cc junk.c >[2]junk" . 344 .PP 345 A file descriptor may be redirected to an already open descriptor by writing 346 .BI >[ fd0 = fd1 ] 347 or 348 .BI <[ fd0 = fd1 ]\f1. 349 .I Fd1 350 is a previously opened file descriptor and 351 .I fd0 352 becomes a new copy (in the sense of 353 .MR dup (3) ) 354 of it. 355 A file descriptor may be closed by writing 356 .BI >[ fd0 =] 357 or 358 .BI <[ fd0 =]\f1. 359 .PP 360 Redirections are executed from left to right. 361 Therefore, 362 .B cc junk.c >/dev/null >[2=1] 363 and 364 .B cc junk.c >[2=1] >/dev/null 365 have different effects: the first puts standard output in 366 .BR /dev/null 367 and then puts diagnostic output in the same place, where the second 368 directs diagnostic output to the terminal and sends standard output to 369 .BR /dev/null . 370 .SS Compound Commands 371 A pair of commands separated by a pipe operator 372 .RB ( | ) 373 is a command. 374 The standard output of the left command is sent through a pipe 375 to the standard input of the right command. 376 The pipe operator may be decorated 377 to use different file descriptors. 378 .BI |[ fd ] 379 connects the output end of the pipe to file descriptor 380 .I fd 381 rather than 1. 382 .BI |[ fd0 = fd1 ] 383 connects output to 384 .I fd1 385 of the left command and input to 386 .I fd0 387 of the right command. 388 .PP 389 A pair of commands separated by 390 .B && 391 or 392 .B || 393 is a command. 394 In either case, the left command is executed and its exit status examined. 395 If the operator is 396 .B && 397 the right command is executed if the left command's status is null. 398 .B || 399 causes the right command to be executed if the left command's status is non-null. 400 .PP 401 The exit status of a command may be inverted (non-null is changed to null, null 402 is changed to non-null) by preceding it with a 403 .BR ! . 404 .PP 405 The 406 .B | 407 operator has highest precedence, and is left-associative (i.e. binds tighter 408 to the left than the right). 409 .B ! 410 has intermediate precedence, and 411 .B && 412 and 413 .B || 414 have the lowest precedence. 415 .PP 416 The unary 417 .B @ 418 operator, with precedence equal to 419 .BR ! , 420 causes its operand to be executed in a subshell. 421 .PP 422 Each of the following is a command. 423 .PD 0 424 .HP 425 .B if ( 426 .I list 427 .B ) 428 .I command 429 .br 430 A 431 .I list 432 is a sequence of commands, separated by 433 .BR & , 434 .BR ; , 435 or newline. 436 It is executed and 437 if its exit status is null, the 438 .I command 439 is executed. 440 .HP 441 .B if not 442 .I command 443 .br 444 The immediately preceding command must have been 445 .BI if( list ) 446 .IR command . 447 If its condition was non-zero, the 448 .I command 449 is executed. 450 .HP 451 .BI for( name 452 .B in 453 .IB arguments ) 454 .I command 455 .HP 456 .BI for( name ) 457 .I command 458 .br 459 The 460 .I command 461 is executed once for each 462 .IR argument 463 with that argument assigned to 464 .IR name . 465 If the argument list is omitted, 466 .B $* 467 is used. 468 .HP 469 .BI while( list ) 470 .I command 471 .br 472 The 473 .I list 474 is executed repeatedly until its exit status is non-null. 475 Each time it returns null status, the 476 .I command 477 is executed. 478 An empty 479 .I list 480 is taken to give null 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 .B cases 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 brace. 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 .BR ; , 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 " note { list } 539 .br 540 .HP 541 .BI "fn " note 542 .br 543 A function with a special name will be called when 544 .I rc 545 receives a corresponding note; see 546 .MR notify (3) . 547 The valid note names (and corresponding notes) are 548 .B sighup 549 .RB ( hangup ), 550 .B sigint 551 .RB ( interrupt ), 552 .BR sigalrm 553 .RB ( alarm ), 554 and 555 .B sigfpe 556 (floating point trap). 557 By default 558 .I rc 559 exits on receiving any signal, except when run interactively, 560 in which case interrupts and quits normally cause 561 .I rc 562 to stop whatever it's doing and start reading a new command. 563 The second form causes 564 .I rc 565 to handle a signal in the default manner. 566 .I Rc 567 recognizes an artificial note, 568 .BR sigexit , 569 which occurs when 570 .I rc 571 is about to finish executing. 572 .HP 573 .IB name = "argument command" 574 .br 575 Any command may be preceded by a sequence of assignments 576 interspersed with redirections. 577 The assignments remain in effect until the end of the command, unless 578 the command is empty (i.e. the assignments stand alone), in which case 579 they are effective until rescinded by later assignments. 580 .PD 581 .SS Built-in Commands 582 These commands are executed internally by 583 .IR rc , 584 usually because their execution changes or depends on 585 .IR rc 's 586 internal state. 587 .PD 0 588 .HP 589 .BI . " file ..." 590 .br 591 Execute commands from 592 .IR file . 593 .B $* 594 is set for the duration to the remainder of the argument list following 595 .IR file . 596 .I File 597 is searched for using 598 .BR $path . 599 .HP 600 .BI builtin " command ..." 601 .br 602 Execute 603 .I command 604 as usual except that any function named 605 .I command 606 is ignored in favor of the built-in meaning. 607 .HP 608 .BI "cd [" dir "]" 609 .br 610 Change the current directory to 611 .IR dir . 612 The default argument is 613 .BR $home . 614 .I dir 615 is searched for in each of the directories mentioned in 616 .BR $cdpath . 617 .HP 618 .BI "eval [" "arg ..." "]" 619 .br 620 The arguments are concatenated separated by spaces into a single string, 621 read as input to 622 .IR rc , 623 and executed. 624 .HP 625 .BI "exec [" "command ..." "]" 626 .br 627 This instance of 628 .I rc 629 replaces itself with the given (non-built-in) 630 .IR command . 631 .HP 632 .BI "flag " f " [+-]" 633 .br 634 Either set 635 .RB ( + ), 636 clear 637 .RB ( - ), 638 or test (neither 639 .B + 640 nor 641 .BR - ) 642 the flag 643 .IR f , 644 where 645 .I f 646 is a single character, one of the command line flags (see Invocation, below). 647 .HP 648 .BI "exit [" status "]" 649 .br 650 Exit with the given exit status. 651 If none is given, the current value of 652 .B $status 653 is used. 654 .HP 655 .BR "rfork " [ nNeEsfFm ] 656 .br 657 Become a new process group using 658 .BI rfork( flags ) 659 where 660 .I flags 661 is composed of the bitwise OR of the 662 .B rfork 663 flags specified by the option letters 664 (see 665 .MR fork (2) ). 666 If no 667 .I flags 668 are given, they default to 669 .BR ens . 670 The 671 .I flags 672 and their meanings are: 673 .B n 674 is 675 .BR RFNAMEG ; 676 .B N 677 is 678 .BR RFCNAMEG ; 679 .B e 680 is 681 .BR RFENVG ; 682 .B E 683 is 684 .BR RFCENVG ; 685 .B s 686 is 687 .BR RFNOTEG ; 688 .B f 689 is 690 .BR RFFDG ; 691 .B F 692 is 693 .BR RFCFDG ; 694 and 695 .B m 696 is 697 .BR RFNOMNT . 698 .HP 699 .BI "shift [" n "]" 700 .br 701 Delete the first 702 .IR n 703 (default 1) 704 elements of 705 .BR $* . 706 .HP 707 .BI "wait [" pid "]" 708 .br 709 Wait for the process with the given 710 .I pid 711 to exit. 712 If no 713 .I pid 714 is given, all outstanding processes are waited for. 715 .HP 716 .BI whatis " name ..." 717 .br 718 Print the value of each 719 .I name 720 in a form suitable for input to 721 .IR rc . 722 The output is 723 an assignment to any variable, 724 the definition of any function, 725 a call to 726 .B builtin 727 for any built-in command, or 728 the completed pathname of any executable file. 729 .HP 730 .BI ~ " subject pattern ..." 731 .br 732 The 733 .I subject 734 is matched against each 735 .I pattern 736 in sequence. 737 If it matches any pattern, 738 .B $status 739 is set to zero. 740 Otherwise, 741 .B $status 742 is set to one. 743 Patterns are the same as for file name matching, except that 744 .B / 745 and the first character of 746 .B . 747 and 748 .B .. 749 need not be matched explicitly. 750 The 751 .I patterns 752 are not subjected to 753 file name matching before the 754 .B ~ 755 command is executed, so they need not be enclosed in quotation marks. 756 .PD 757 .SS Environment 758 The 759 .I environment 760 is a list of strings made available to executing binaries by the 761 kernel. 762 .I Rc 763 creates an environment entry for each variable whose value is non-empty, 764 and for each function. 765 The string for a variable entry has the variable's name followed by 766 .B = 767 and its value. 768 If the value has more than one component, these 769 are separated by SOH (001) 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 Defaults to 810 .B $HOME 811 or else 812 .LR / . 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 .MR 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 The 972 .BI <{ command } 973 syntax depends on the underlying operating system 974 providing a file descriptor device tree at 975 .BR /dev/fd . 976 .PP 977 Some FreeBSD installations 978 does not provide file descriptors greater than 2 979 in 980 .BR /dev/fd . 981 To fix this, add 982 .IP 983 .EX 984 /fdescfs /dev/fd fdescfs rw 0 0 985 .EE 986 .LP 987 to 988 .BR /etc/fstab , 989 and then 990 .B mount 991 .BR /dev/fd . 992 (Adding the line to 993 .B fstab 994 ensures causes FreeBSD to mount the file system 995 automatically at boot time.) 996 .PP 997 Some systems require 998 .B \*9/bin/rc 999 to be listed in 1000 .B /etc/shells 1001 before it can be used as a login shell.