3 rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ \- command language
25 It executes command lines read from a terminal or a file or, with the
31 A command line is a sequence of commands, separated by ampersands or semicolons
35 terminated by a newline.
36 The commands are executed in sequence
39 does not wait for a command followed by
41 to finish executing before starting
42 the following command.
43 Whenever a command followed by
45 is executed, its process id is assigned to the
53 exits or is terminated, the
57 gets the process's wait message (see
59 it will be the null string if the command was successful.
61 A long command line may be continued on subsequent lines by typing
64 followed by a newline.
65 This sequence is treated as though it were a blank.
66 Backslash is not otherwise a special character.
70 and any following characters up to (but not including) the next newline
71 are ignored, except in quotation marks.
73 A simple command is a sequence of arguments interspersed with I/O redirections.
74 If the first argument is the name of an
78 built-in commands, it is executed by
80 Otherwise if the name starts with a slash
82 it must be the path name of the program to be executed.
83 Names containing no initial slash are searched for in
84 a list of directory names stored in
86 The first executable file of the given name found
89 is the program to be executed.
90 To be executable, the user must have execute permission (see
92 and the file must be either an executable binary
93 for the current machine's CPU type, or a shell script.
94 Shell scripts begin with a line containing the full path name of a shell
100 The first word of a simple command cannot be a keyword unless it is
101 quoted or otherwise disguised.
104 for in while if not switch fn ~ ! @
106 .SS Arguments and Variables
107 A number of constructions may be used where
109 syntax requires an argument to appear.
110 In many cases a construction's
111 value will be a list of arguments rather than a single string.
113 The simplest kind of argument is the unquoted word:
114 a sequence of one or more characters none of which is a blank, tab,
115 newline, or any of the following:
117 # ; & | ^ $ = ` ' { } ( ) < >
119 An unquoted word that contains any of the characters
123 is a pattern for matching against file names.
126 matches any sequence of characters,
128 matches any single character, and
130 matches any character in the
132 If the first character of
136 the class is complemented.
139 may also contain pairs of characters separated by
141 standing for all characters lexically between the two.
144 must appear explicitly in a pattern, as must the
145 first character of the path name components
149 A pattern is replaced by a list of arguments, one for each path name matched,
150 except that a pattern matching no names is not replaced by the empty list,
151 but rather stands for itself.
152 Pattern matching is done after all other
165 A quoted word is a sequence of characters surrounded by single quotes
167 A single quote is represented in a quoted word by a pair of quotes
170 Each of the following is an argument.
175 The value of a sequence of arguments enclosed in parentheses is
176 a list comprising the members of each element of the sequence.
177 Argument lists have no recursive structure, although their syntax may
179 The following are entirely equivalent:
181 echo hi there everybody
182 ((echo) (hi there) everybody)
187 .BI $ argument ( subscript )
193 is the name of a variable whose value is substituted.
195 of indirection are possible, but of questionable utility.
197 are lists of strings.
210 elements, in which case the value is empty.
213 is followed by a parenthesized list of subscripts, the
214 value substituted is a list composed of the requested elements (origin 1).
215 The parenthesis must follow the variable name with no spaces.
216 Subscripts can also take the form
220 to indicate a sequence of elements.
221 Assignments to variables are described below.
225 The value is the number of elements in the named variable.
227 never assigned a value has zero elements.
232 The value is a single string containing the components of the named variable
233 separated by spaces. A variable with zero elements yields the empty string.
237 .BI ` "split " { command }
242 and reads its standard output, splitting it into a list of arguments,
248 is not otherwise set, its value is
250 In the second form of the command, split is used instead of
259 is executed asynchronously with its standard output or standard input
261 The value of the argument is the name of a file
262 referring to the other end of the pipe.
263 This allows the construction of
264 non-linear pipelines.
265 For example, the following runs two commands
271 to compare their outputs
276 .IB argument ^ argument
280 operator concatenates its two operands.
282 have the same number of components, they are concatenated pairwise.
284 then one operand must have one component, and the other must be non-empty,
285 and concatenation is distributive.
288 In most circumstances,
292 operator automatically between words that are not separated by white space.
297 follows a quoted or unquoted word or an unquoted word follows a quoted word
298 with no intervening blanks or tabs,
301 is inserted between the two.
302 If an unquoted word immediately follows a
304 and contains a character other than an alphanumeric, underscore,
309 is inserted before the first such character.
312 .B cc -$flags $stem.c
316 .B cc -^$flags $stem^.c
320 redirects the standard output file (file descriptor 1, normally the
321 terminal) to the named
324 appends standard output to the file.
325 The standard input file (file descriptor 0, also normally the terminal)
326 may be redirected from a file by the sequence
328 or from an inline `here document'
330 .BI << eof-marker\f1.
331 The contents of a here document are lines of text taken from the command
332 input stream up to a line containing nothing but the
334 which may be either a quoted or unquoted word.
337 is unquoted, variable names of the form
339 have their values substituted from
344 is followed by a caret
346 the caret is deleted.
349 is quoted, no substitution occurs.
350 The standard input file
351 may also be redirected from a file by the sequence
355 exactly once, for reading and writing.
357 Redirections may be applied to a file-descriptor other than standard input
358 or output by qualifying the redirection operator
359 with a number in square brackets.
360 For example, the diagnostic output (file descriptor 2)
361 may be redirected by writing
362 .BR "cc junk.c >[2]junk" .
364 A file descriptor may be redirected to an already open descriptor by writing
368 .BI <[ fd0 = fd1 ]\f1.
370 is a previously opened file descriptor and
372 becomes a new copy (in the sense of
375 A file descriptor may be closed by writing
380 Redirections are executed from left to right.
382 .B cc junk.c >/dev/null >[2=1]
384 .B cc junk.c >[2=1] >/dev/null
385 have different effects: the first puts standard output in
387 and then puts diagnostic output in the same place, where the second
388 directs diagnostic output to the terminal and sends standard output to
391 .B newconn <>/net/tcp/clone >[1=0]
394 exactly once for reading and writing and puts it on standard input and output.
395 .B lpd <>[3]/net/tcp/42/data
398 exactly once for reading and writing and puts it on file descriptor 3.
399 .SS Compound Commands
400 A pair of commands separated by a pipe operator
403 The standard output of the left command is sent through a pipe
404 to the standard input of the right command.
405 The pipe operator may be decorated
406 to use different file descriptors.
408 connects the output end of the pipe to file descriptor
414 of the left command and input to
416 of the right command.
418 A pair of commands separated by
423 In either case, the left command is executed and its exit status examined.
426 the right command is executed if the left command's status is null.
428 causes the right command to be executed if the left command's status is non-null.
430 The exit status of a command may be inverted (non-null is changed to null, null
431 is changed to non-null) by preceding it with a
436 operator has highest precedence, and is left-associative (i.e. binds tighter
437 to the left than the right).
439 has intermediate precedence, and
443 have the lowest precedence.
447 operator, with precedence equal to
449 causes its operand to be executed in a subshell.
451 Each of the following is a command.
461 is a sequence of commands, separated by
466 if its exit status is null, the
473 The immediately preceding command must have been
476 If its condition was non-zero, the
490 is executed once for each
492 with that argument assigned to
494 If the argument list is omitted,
503 is executed repeatedly until its exit status is non-null.
504 Each time it returns null status, the
509 is taken to give null status.
511 .BI "switch(" argument "){" list }
515 is searched for simple commands beginning with the word
517 (The search is only at the `top level' of the
521 in nested constructs are not found.)
523 is matched against each word following
525 using the pattern-matching algorithm described above, except that
527 and the first characters of
531 need not be matched explicitly.
532 When a match is found, commands in the list are executed up to the next
535 command (at the top level) or the closing brace.
539 Braces serve to alter the grouping of commands implied by operator
543 is a sequence of commands separated by
548 .BI "fn " name { list }
552 The first form defines a function with the given
554 Subsequently, whenever a command whose first argument is
556 is encountered, the current value of
557 the remainder of the command's argument list will be assigned to
559 after saving its current value, and
563 The second form removes
567 .BI "fn " note { list }
572 A function with a special name will be called when
574 receives a corresponding note; see
576 The valid note names (and corresponding notes) are
585 (floating point trap).
588 exits on receiving any signal, except when run interactively,
589 in which case interrupts and quits normally cause
591 to stop whatever it's doing and start reading a new command.
592 The second form causes
594 to handle a signal in the default manner.
596 recognizes an artificial note,
600 is about to finish executing.
602 .IB name = "argument command"
604 Any command may be preceded by a sequence of assignments
605 interspersed with redirections.
606 The assignments remain in effect until the end of the command, unless
607 the command is empty (i.e. the assignments stand alone), in which case
608 they are effective until rescinded by later assignments.
610 .SS Built-in Commands
611 These commands are executed internally by
613 usually because their execution changes or depends on
620 Execute commands from
623 is set for the duration to the remainder of the argument list following
626 is searched for using
629 .BI builtin " command ..."
633 as usual except that any function named
635 is ignored in favor of the built-in meaning.
639 Change the current directory to
641 The default argument is
644 is searched for in each of the directories mentioned in
647 .BI "eval [" "arg ..." "]"
649 The arguments are concatenated separated by spaces into a single string,
654 .BI "exec [" "command ..." "]"
658 replaces itself with the given (non-built-in)
661 .BI "flag " f " [+-]"
675 is a single character, one of the command line flags (see Invocation, below).
677 .BI "exit [" status "]"
679 Exit with the given exit status.
680 If none is given, the current value of
684 .BR "rfork " [ nNeEsfFm ]
686 Become a new process group using
690 is composed of the bitwise OR of the
692 flags specified by the option letters
697 are given, they default to
701 and their meanings are:
738 Wait for the process with the given
743 is given, all outstanding processes are waited for.
745 .BI whatis " name ..."
747 Print the value of each
749 in a form suitable for input to
752 an assignment to any variable,
753 the definition of any function,
756 for any built-in command, or
757 the completed pathname of any executable file.
759 .BI ~ " subject pattern ..."
763 is matched against each
766 If it matches any pattern,
772 Patterns are the same as for file name matching, except that
774 and the first character of
778 need not be matched explicitly.
782 file name matching before the
784 command is executed, so they need not be enclosed in quotation marks.
789 is a list of strings made available to executing binaries by the
795 creates an environment entry for each variable whose value is non-empty,
796 and for each function.
797 The string for a variable entry has the variable's name followed by
800 If the value has more than one component, these
804 The string for a function is just the
806 input that defines the function.
807 The name of a function in the environment is the function name
813 starts executing it reads variable and function definitions from its
815 .SS Special Variables
816 The following variables are set or used by
819 .TP \w'\fL$promptXX'u
823 argument list during initialization.
826 command or a function is executed, the current value is saved and
828 receives the new argument list.
829 The saved value is restored on completion of the
834 Whenever a process is started asynchronously with
837 is set to its process id.
840 The default directory for
844 The input field separators used in backquote substitutions.
847 is not otherwise set, its value is
851 The search path used to find commands and input files
855 If not set in the environment, it is initialized by
856 .BR "path=(.\ /bin)" .
857 Its use is discouraged; instead use
861 containing what's needed.
864 Set during initialization to
871 is run interactively, the first component of
873 is printed before reading each command.
874 The second component is printed whenever a newline is typed and more lines
875 are required to complete the command.
876 If not set in the environment, it is initialized by
877 .BR "prompt=('%\ '\ '\ ')" .
880 Set to the wait message of the last-executed program.
888 Its value is used to control execution in
897 exits at end-of-file of its input or on executing an
899 command with no argument,
906 is started with no arguments it reads commands from standard input.
907 Otherwise its first non-flag argument is the name of a file from which
908 to read commands (but see
911 Subsequent arguments become the initial value of
914 accepts the following command-line flags.
916 .TP \w'\fL-c\ \fIstring\fLXX'u
918 Commands are read from
922 Print out exit status after any command where the status is non-null.
927 is non-null after executing a simple command.
934 is given no arguments and its standard input is a terminal,
935 it runs interactively.
936 Commands are prompted for using
942 is not run interactively.
947 is given or the first character of argument zero is
951 .BR $home/lib/profile ,
952 if it exists, before reading its normal input.
955 Read commands to initialize
969 Echo input on file descriptor 2 as it is read.
972 Print each simple command before executing it.
975 Print debugging information (internal form of commands
976 as they are executed).
979 .TF $home/lib/profile
982 the user's local rc start script
986 System rc start script
987 .TF /rc/lib/rcmain.local
989 .B /rc/lib/rcmain.local
990 Site specific system rc start script
995 ``Rc \- The Plan 9 Shell''.
997 There should be a way to match patterns against whole lists rather than
1002 to check the value of
1007 Functions containing here documents don't work.
1009 Free carets don't get inserted next to keywords.