3 cfa37a7b 2004-04-10 devnull rc, cd, eval, exec, exit, flag, rfork, shift, wait, whatis, ., ~ \- command language
4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
7 cfa37a7b 2004-04-10 devnull .B -srdiIlxepvV
10 cfa37a7b 2004-04-10 devnull .B -c command
15 cfa37a7b 2004-04-10 devnull .I arg ...
17 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
19 cfa37a7b 2004-04-10 devnull is the Plan 9 shell.
20 cfa37a7b 2004-04-10 devnull It executes command lines read from a terminal or a file or, with the
22 cfa37a7b 2004-04-10 devnull flag, from
24 cfa37a7b 2004-04-10 devnull argument list.
25 cfa37a7b 2004-04-10 devnull .SS Command Lines
26 cfa37a7b 2004-04-10 devnull A command line is a sequence of commands, separated by ampersands or semicolons
30 cfa37a7b 2004-04-10 devnull terminated by a newline.
31 cfa37a7b 2004-04-10 devnull The commands are executed in sequence
32 cfa37a7b 2004-04-10 devnull from left to right.
34 cfa37a7b 2004-04-10 devnull does not wait for a command followed by
36 cfa37a7b 2004-04-10 devnull to finish executing before starting
37 cfa37a7b 2004-04-10 devnull the following command.
38 cfa37a7b 2004-04-10 devnull Whenever a command followed by
40 cfa37a7b 2004-04-10 devnull is executed, its process id is assigned to the
43 cfa37a7b 2004-04-10 devnull .BR $apid .
44 cfa37a7b 2004-04-10 devnull Whenever a command
46 cfa37a7b 2004-04-10 devnull followed by
48 cfa37a7b 2004-04-10 devnull exits or is terminated, the
51 cfa37a7b 2004-04-10 devnull .B $status
52 cfa37a7b 2004-04-10 devnull gets the process's wait message (see
53 058b0118 2005-01-03 devnull .IR wait (3));
54 cfa37a7b 2004-04-10 devnull it will be the null string if the command was successful.
56 cfa37a7b 2004-04-10 devnull A long command line may be continued on subsequent lines by typing
57 cfa37a7b 2004-04-10 devnull a backslash
58 cfa37a7b 2004-04-10 devnull .RB ( \e )
59 cfa37a7b 2004-04-10 devnull followed by a newline.
60 cfa37a7b 2004-04-10 devnull This sequence is treated as though it were a blank.
61 cfa37a7b 2004-04-10 devnull Backslash is not otherwise a special character.
63 cfa37a7b 2004-04-10 devnull A number-sign
64 cfa37a7b 2004-04-10 devnull .RB ( # )
65 cfa37a7b 2004-04-10 devnull and any following characters up to (but not including) the next newline
66 cfa37a7b 2004-04-10 devnull are ignored, except in quotation marks.
67 cfa37a7b 2004-04-10 devnull .SS Simple Commands
68 cfa37a7b 2004-04-10 devnull A simple command is a sequence of arguments interspersed with I/O redirections.
69 cfa37a7b 2004-04-10 devnull If the first argument is the name of an
71 cfa37a7b 2004-04-10 devnull function or of one of
73 cfa37a7b 2004-04-10 devnull built-in commands, it is executed by
75 cfa37a7b 2004-04-10 devnull Otherwise if the name starts with a slash
76 cfa37a7b 2004-04-10 devnull .RB ( / ),
77 cfa37a7b 2004-04-10 devnull it must be the path name of the program to be executed.
78 cfa37a7b 2004-04-10 devnull Names containing no initial slash are searched for in
79 cfa37a7b 2004-04-10 devnull a list of directory names stored in
80 cfa37a7b 2004-04-10 devnull .BR $path .
81 cfa37a7b 2004-04-10 devnull The first executable file of the given name found
82 cfa37a7b 2004-04-10 devnull in a directory in
84 cfa37a7b 2004-04-10 devnull is the program to be executed.
85 cfa37a7b 2004-04-10 devnull To be executable, the user must have execute permission (see
86 058b0118 2005-01-03 devnull .IR stat (3))
87 cfa37a7b 2004-04-10 devnull and the file must be either an executable binary
88 cfa37a7b 2004-04-10 devnull for the current machine's CPU type, or a shell script.
89 cfa37a7b 2004-04-10 devnull Shell scripts begin with a line containing the full path name of a shell
91 cfa37a7b 2004-04-10 devnull .BR /bin/rc ),
92 cfa37a7b 2004-04-10 devnull prefixed by
95 cfa37a7b 2004-04-10 devnull The first word of a simple command cannot be a keyword unless it is
96 cfa37a7b 2004-04-10 devnull quoted or otherwise disguised.
97 cfa37a7b 2004-04-10 devnull The keywords are
99 cfa37a7b 2004-04-10 devnull for in while if not switch fn ~ ! @
101 cfa37a7b 2004-04-10 devnull .SS Arguments and Variables
102 cfa37a7b 2004-04-10 devnull A number of constructions may be used where
104 cfa37a7b 2004-04-10 devnull syntax requires an argument to appear.
105 cfa37a7b 2004-04-10 devnull In many cases a construction's
106 cfa37a7b 2004-04-10 devnull value will be a list of arguments rather than a single string.
108 cfa37a7b 2004-04-10 devnull The simplest kind of argument is the unquoted word:
109 cfa37a7b 2004-04-10 devnull a sequence of one or more characters none of which is a blank, tab,
110 cfa37a7b 2004-04-10 devnull newline, or any of the following:
112 cfa37a7b 2004-04-10 devnull # ; & | ^ $ = ` ' { } ( ) < >
114 cfa37a7b 2004-04-10 devnull An unquoted word that contains any of the characters
118 cfa37a7b 2004-04-10 devnull is a pattern for matching against file names.
119 cfa37a7b 2004-04-10 devnull The character
121 cfa37a7b 2004-04-10 devnull matches any sequence of characters,
123 cfa37a7b 2004-04-10 devnull matches any single character, and
124 cfa37a7b 2004-04-10 devnull .BI [ class ]
125 cfa37a7b 2004-04-10 devnull matches any character in the
126 cfa37a7b 2004-04-10 devnull .IR class .
127 cfa37a7b 2004-04-10 devnull If the first character of
128 cfa37a7b 2004-04-10 devnull .I class
131 cfa37a7b 2004-04-10 devnull the class is complemented.
133 cfa37a7b 2004-04-10 devnull .I class
134 cfa37a7b 2004-04-10 devnull may also contain pairs of characters separated by
136 cfa37a7b 2004-04-10 devnull standing for all characters lexically between the two.
137 cfa37a7b 2004-04-10 devnull The character
139 cfa37a7b 2004-04-10 devnull must appear explicitly in a pattern, as must the
140 cfa37a7b 2004-04-10 devnull first character of the path name components
143 cfa37a7b 2004-04-10 devnull .BR .. .
144 cfa37a7b 2004-04-10 devnull A pattern is replaced by a list of arguments, one for each path name matched,
145 cfa37a7b 2004-04-10 devnull except that a pattern matching no names is not replaced by the empty list,
146 cfa37a7b 2004-04-10 devnull but rather stands for itself.
147 cfa37a7b 2004-04-10 devnull Pattern matching is done after all other
148 cfa37a7b 2004-04-10 devnull operations.
151 cfa37a7b 2004-04-10 devnull x=/tmp echo $x^/*.c
154 cfa37a7b 2004-04-10 devnull .BR /tmp/*.c ,
155 cfa37a7b 2004-04-10 devnull rather than matching
156 cfa37a7b 2004-04-10 devnull .B "/*.c
157 cfa37a7b 2004-04-10 devnull and then prefixing
158 cfa37a7b 2004-04-10 devnull .BR /tmp .
160 cfa37a7b 2004-04-10 devnull A quoted word is a sequence of characters surrounded by single quotes
161 cfa37a7b 2004-04-10 devnull .RB ( ' ).
162 cfa37a7b 2004-04-10 devnull A single quote is represented in a quoted word by a pair of quotes
163 cfa37a7b 2004-04-10 devnull .RB ( '' ).
165 cfa37a7b 2004-04-10 devnull Each of the following is an argument.
168 cfa37a7b 2004-04-10 devnull .BI ( arguments )
170 cfa37a7b 2004-04-10 devnull The value of a sequence of arguments enclosed in parentheses is
171 cfa37a7b 2004-04-10 devnull a list comprising the members of each element of the sequence.
172 cfa37a7b 2004-04-10 devnull Argument lists have no recursive structure, although their syntax may
173 cfa37a7b 2004-04-10 devnull suggest it.
174 cfa37a7b 2004-04-10 devnull The following are entirely equivalent:
176 cfa37a7b 2004-04-10 devnull echo hi there everybody
177 cfa37a7b 2004-04-10 devnull ((echo) (hi there) everybody)
180 cfa37a7b 2004-04-10 devnull .BI $ argument
182 cfa37a7b 2004-04-10 devnull .BI $ argument ( subscript )
185 cfa37a7b 2004-04-10 devnull .I argument
186 cfa37a7b 2004-04-10 devnull after the
188 cfa37a7b 2004-04-10 devnull is the name of a variable whose value is substituted.
189 cfa37a7b 2004-04-10 devnull Multiple levels
190 cfa37a7b 2004-04-10 devnull of indirection are possible, but of questionable utility.
191 cfa37a7b 2004-04-10 devnull Variable values
192 cfa37a7b 2004-04-10 devnull are lists of strings.
194 cfa37a7b 2004-04-10 devnull .I argument
195 cfa37a7b 2004-04-10 devnull is a number
197 cfa37a7b 2004-04-10 devnull the value is the
198 cfa37a7b 2004-04-10 devnull .IR n th
199 cfa37a7b 2004-04-10 devnull element of
200 cfa37a7b 2004-04-10 devnull .BR $* ,
203 cfa37a7b 2004-04-10 devnull doesn't have
205 cfa37a7b 2004-04-10 devnull elements, in which case the value is empty.
207 cfa37a7b 2004-04-10 devnull .I argument
208 cfa37a7b 2004-04-10 devnull is followed by a parenthesized list of subscripts, the
209 cfa37a7b 2004-04-10 devnull value substituted is a list composed of the requested elements (origin 1).
210 cfa37a7b 2004-04-10 devnull The parenthesis must follow the variable name with no spaces.
211 cfa37a7b 2004-04-10 devnull Assignments to variables are described below.
213 cfa37a7b 2004-04-10 devnull .BI $# argument
215 cfa37a7b 2004-04-10 devnull The value is the number of elements in the named variable.
216 cfa37a7b 2004-04-10 devnull A variable
217 cfa37a7b 2004-04-10 devnull never assigned a value has zero elements.
220 cfa37a7b 2004-04-10 devnull .I argument
222 cfa37a7b 2004-04-10 devnull The value is a single string containing the components of the named variable
223 cfa37a7b 2004-04-10 devnull separated by spaces. A variable with zero elements yields the empty string.
225 cfa37a7b 2004-04-10 devnull .BI `{ command }
228 cfa37a7b 2004-04-10 devnull executes the
229 cfa37a7b 2004-04-10 devnull .I command
230 cfa37a7b 2004-04-10 devnull and reads its standard output, splitting it into a list of arguments,
231 cfa37a7b 2004-04-10 devnull using characters in
233 cfa37a7b 2004-04-10 devnull as separators.
236 cfa37a7b 2004-04-10 devnull is not otherwise set, its value is
237 cfa37a7b 2004-04-10 devnull .BR "'\ \et\en'" .
239 cfa37a7b 2004-04-10 devnull .BI <{ command }
241 cfa37a7b 2004-04-10 devnull .BI >{ command }
244 cfa37a7b 2004-04-10 devnull .I command
245 cfa37a7b 2004-04-10 devnull is executed asynchronously with its standard output or standard input
246 cfa37a7b 2004-04-10 devnull connected to a pipe.
247 cfa37a7b 2004-04-10 devnull The value of the argument is the name of a file
248 cfa37a7b 2004-04-10 devnull referring to the other end of the pipe.
249 cfa37a7b 2004-04-10 devnull This allows the construction of
250 cfa37a7b 2004-04-10 devnull non-linear pipelines.
251 cfa37a7b 2004-04-10 devnull For example, the following runs two commands
255 cfa37a7b 2004-04-10 devnull and uses
257 cfa37a7b 2004-04-10 devnull to compare their outputs
259 cfa37a7b 2004-04-10 devnull cmp <{old} <{new}
262 cfa37a7b 2004-04-10 devnull .IB argument ^ argument
266 cfa37a7b 2004-04-10 devnull operator concatenates its two operands.
267 cfa37a7b 2004-04-10 devnull If the two operands
268 cfa37a7b 2004-04-10 devnull have the same number of components, they are concatenated pairwise.
270 cfa37a7b 2004-04-10 devnull then one operand must have one component, and the other must be non-empty,
271 cfa37a7b 2004-04-10 devnull and concatenation is distributive.
273 cfa37a7b 2004-04-10 devnull .SS Free Carets
274 cfa37a7b 2004-04-10 devnull In most circumstances,
276 cfa37a7b 2004-04-10 devnull will insert the
278 cfa37a7b 2004-04-10 devnull operator automatically between words that are not separated by white space.
279 cfa37a7b 2004-04-10 devnull Whenever one of
283 cfa37a7b 2004-04-10 devnull follows a quoted or unquoted word or an unquoted word follows a quoted word
284 cfa37a7b 2004-04-10 devnull with no intervening blanks or tabs,
287 cfa37a7b 2004-04-10 devnull is inserted between the two.
288 cfa37a7b 2004-04-10 devnull If an unquoted word immediately follows a
290 cfa37a7b 2004-04-10 devnull and contains a character other than an alphanumeric, underscore,
295 cfa37a7b 2004-04-10 devnull is inserted before the first such character.
298 cfa37a7b 2004-04-10 devnull .B cc -$flags $stem.c
300 cfa37a7b 2004-04-10 devnull is equivalent to
302 cfa37a7b 2004-04-10 devnull .B cc -^$flags $stem^.c
303 cfa37a7b 2004-04-10 devnull .SS I/O Redirections
304 cfa37a7b 2004-04-10 devnull The sequence
305 cfa37a7b 2004-04-10 devnull .BI > file
306 cfa37a7b 2004-04-10 devnull redirects the standard output file (file descriptor 1, normally the
307 cfa37a7b 2004-04-10 devnull terminal) to the named
308 cfa37a7b 2004-04-10 devnull .IR file ;
309 cfa37a7b 2004-04-10 devnull .BI >> file
310 cfa37a7b 2004-04-10 devnull appends standard output to the file.
311 cfa37a7b 2004-04-10 devnull The standard input file (file descriptor 0, also normally the terminal)
312 cfa37a7b 2004-04-10 devnull may be redirected from a file by the sequence
313 cfa37a7b 2004-04-10 devnull .BI < file \f1,
314 cfa37a7b 2004-04-10 devnull or from an inline `here document'
315 cfa37a7b 2004-04-10 devnull by the sequence
316 cfa37a7b 2004-04-10 devnull .BI << eof-marker\f1.
317 cfa37a7b 2004-04-10 devnull The contents of a here document are lines of text taken from the command
318 cfa37a7b 2004-04-10 devnull input stream up to a line containing nothing but the
319 cfa37a7b 2004-04-10 devnull .IR eof-marker ,
320 cfa37a7b 2004-04-10 devnull which may be either a quoted or unquoted word.
322 cfa37a7b 2004-04-10 devnull .I eof-marker
323 cfa37a7b 2004-04-10 devnull is unquoted, variable names of the form
324 cfa37a7b 2004-04-10 devnull .BI $ word
325 cfa37a7b 2004-04-10 devnull have their values substituted from
327 cfa37a7b 2004-04-10 devnull environment.
329 cfa37a7b 2004-04-10 devnull .BI $ word
330 cfa37a7b 2004-04-10 devnull is followed by a caret
331 cfa37a7b 2004-04-10 devnull .RB ( ^ ),
332 cfa37a7b 2004-04-10 devnull the caret is deleted.
334 cfa37a7b 2004-04-10 devnull .I eof-marker
335 cfa37a7b 2004-04-10 devnull is quoted, no substitution occurs.
337 cfa37a7b 2004-04-10 devnull Redirections may be applied to a file-descriptor other than standard input
338 cfa37a7b 2004-04-10 devnull or output by qualifying the redirection operator
339 cfa37a7b 2004-04-10 devnull with a number in square brackets.
340 cfa37a7b 2004-04-10 devnull For example, the diagnostic output (file descriptor 2)
341 cfa37a7b 2004-04-10 devnull may be redirected by writing
342 cfa37a7b 2004-04-10 devnull .BR "cc junk.c >[2]junk" .
344 cfa37a7b 2004-04-10 devnull A file descriptor may be redirected to an already open descriptor by writing
345 cfa37a7b 2004-04-10 devnull .BI >[ fd0 = fd1 ]
347 cfa37a7b 2004-04-10 devnull .BI <[ fd0 = fd1 ]\f1.
349 cfa37a7b 2004-04-10 devnull is a previously opened file descriptor and
351 cfa37a7b 2004-04-10 devnull becomes a new copy (in the sense of
352 058b0118 2005-01-03 devnull .IR dup (3))
354 cfa37a7b 2004-04-10 devnull A file descriptor may be closed by writing
355 cfa37a7b 2004-04-10 devnull .BI >[ fd0 =]
357 cfa37a7b 2004-04-10 devnull .BI <[ fd0 =]\f1.
359 cfa37a7b 2004-04-10 devnull Redirections are executed from left to right.
360 cfa37a7b 2004-04-10 devnull Therefore,
361 cfa37a7b 2004-04-10 devnull .B cc junk.c >/dev/null >[2=1]
363 cfa37a7b 2004-04-10 devnull .B cc junk.c >[2=1] >/dev/null
364 cfa37a7b 2004-04-10 devnull have different effects: the first puts standard output in
365 cfa37a7b 2004-04-10 devnull .BR /dev/null
366 cfa37a7b 2004-04-10 devnull and then puts diagnostic output in the same place, where the second
367 cfa37a7b 2004-04-10 devnull directs diagnostic output to the terminal and sends standard output to
368 cfa37a7b 2004-04-10 devnull .BR /dev/null .
369 cfa37a7b 2004-04-10 devnull .SS Compound Commands
370 cfa37a7b 2004-04-10 devnull A pair of commands separated by a pipe operator
371 cfa37a7b 2004-04-10 devnull .RB ( | )
372 cfa37a7b 2004-04-10 devnull is a command.
373 cfa37a7b 2004-04-10 devnull The standard output of the left command is sent through a pipe
374 cfa37a7b 2004-04-10 devnull to the standard input of the right command.
375 cfa37a7b 2004-04-10 devnull The pipe operator may be decorated
376 cfa37a7b 2004-04-10 devnull to use different file descriptors.
377 cfa37a7b 2004-04-10 devnull .BI |[ fd ]
378 cfa37a7b 2004-04-10 devnull connects the output end of the pipe to file descriptor
380 cfa37a7b 2004-04-10 devnull rather than 1.
381 cfa37a7b 2004-04-10 devnull .BI |[ fd0 = fd1 ]
382 cfa37a7b 2004-04-10 devnull connects output to
384 cfa37a7b 2004-04-10 devnull of the left command and input to
386 cfa37a7b 2004-04-10 devnull of the right command.
388 cfa37a7b 2004-04-10 devnull A pair of commands separated by
392 cfa37a7b 2004-04-10 devnull is a command.
393 cfa37a7b 2004-04-10 devnull In either case, the left command is executed and its exit status examined.
394 cfa37a7b 2004-04-10 devnull If the operator is
396 cfa37a7b 2004-04-10 devnull the right command is executed if the left command's status is null.
398 cfa37a7b 2004-04-10 devnull causes the right command to be executed if the left command's status is non-null.
400 cfa37a7b 2004-04-10 devnull The exit status of a command may be inverted (non-null is changed to null, null
401 cfa37a7b 2004-04-10 devnull is changed to non-null) by preceding it with a
406 cfa37a7b 2004-04-10 devnull operator has highest precedence, and is left-associative (i.e. binds tighter
407 cfa37a7b 2004-04-10 devnull to the left than the right).
409 cfa37a7b 2004-04-10 devnull has intermediate precedence, and
413 cfa37a7b 2004-04-10 devnull have the lowest precedence.
415 cfa37a7b 2004-04-10 devnull The unary
417 cfa37a7b 2004-04-10 devnull operator, with precedence equal to
419 cfa37a7b 2004-04-10 devnull causes its operand to be executed in a subshell.
421 cfa37a7b 2004-04-10 devnull Each of the following is a command.
427 cfa37a7b 2004-04-10 devnull .I command
431 cfa37a7b 2004-04-10 devnull is a sequence of commands, separated by
434 cfa37a7b 2004-04-10 devnull or newline.
435 cfa37a7b 2004-04-10 devnull It is executed and
436 cfa37a7b 2004-04-10 devnull if its exit status is null, the
437 cfa37a7b 2004-04-10 devnull .I command
438 cfa37a7b 2004-04-10 devnull is executed.
440 cfa37a7b 2004-04-10 devnull .B if not
441 cfa37a7b 2004-04-10 devnull .I command
443 cfa37a7b 2004-04-10 devnull The immediately preceding command must have been
444 cfa37a7b 2004-04-10 devnull .BI if( list )
445 cfa37a7b 2004-04-10 devnull .IR command .
446 cfa37a7b 2004-04-10 devnull If its condition was non-zero, the
447 cfa37a7b 2004-04-10 devnull .I command
448 cfa37a7b 2004-04-10 devnull is executed.
450 cfa37a7b 2004-04-10 devnull .BI for( name
452 cfa37a7b 2004-04-10 devnull .IB arguments )
453 cfa37a7b 2004-04-10 devnull .I command
455 cfa37a7b 2004-04-10 devnull .BI for( name )
456 cfa37a7b 2004-04-10 devnull .I command
459 cfa37a7b 2004-04-10 devnull .I command
460 cfa37a7b 2004-04-10 devnull is executed once for each
461 cfa37a7b 2004-04-10 devnull .IR argument
462 cfa37a7b 2004-04-10 devnull with that argument assigned to
463 cfa37a7b 2004-04-10 devnull .IR name .
464 cfa37a7b 2004-04-10 devnull If the argument list is omitted,
466 cfa37a7b 2004-04-10 devnull is used.
468 cfa37a7b 2004-04-10 devnull .BI while( list )
469 cfa37a7b 2004-04-10 devnull .I command
473 cfa37a7b 2004-04-10 devnull is executed repeatedly until its exit status is non-null.
474 cfa37a7b 2004-04-10 devnull Each time it returns null status, the
475 cfa37a7b 2004-04-10 devnull .I command
476 cfa37a7b 2004-04-10 devnull is executed.
477 cfa37a7b 2004-04-10 devnull An empty
479 cfa37a7b 2004-04-10 devnull is taken to give null status.
481 cfa37a7b 2004-04-10 devnull .BI "switch(" argument "){" list }
484 cfa37a7b 2004-04-10 devnull .IR list
485 cfa37a7b 2004-04-10 devnull is searched for simple commands beginning with the word
486 cfa37a7b 2004-04-10 devnull .BR case .
487 cfa37a7b 2004-04-10 devnull (The search is only at the `top level' of the
488 cfa37a7b 2004-04-10 devnull .IR list .
489 cfa37a7b 2004-04-10 devnull That is,
490 cfa37a7b 2004-04-10 devnull .B cases
491 cfa37a7b 2004-04-10 devnull in nested constructs are not found.)
492 cfa37a7b 2004-04-10 devnull .I Argument
493 cfa37a7b 2004-04-10 devnull is matched against each word following
495 cfa37a7b 2004-04-10 devnull using the pattern-matching algorithm described above, except that
497 cfa37a7b 2004-04-10 devnull and the first characters of
501 cfa37a7b 2004-04-10 devnull need not be matched explicitly.
502 cfa37a7b 2004-04-10 devnull When a match is found, commands in the list are executed up to the next
503 cfa37a7b 2004-04-10 devnull following
505 cfa37a7b 2004-04-10 devnull command (at the top level) or the closing brace.
507 cfa37a7b 2004-04-10 devnull .BI { list }
509 cfa37a7b 2004-04-10 devnull Braces serve to alter the grouping of commands implied by operator
510 cfa37a7b 2004-04-10 devnull priorities.
513 cfa37a7b 2004-04-10 devnull is a sequence of commands separated by
516 cfa37a7b 2004-04-10 devnull or newline.
518 cfa37a7b 2004-04-10 devnull .BI "fn " name { list }
520 cfa37a7b 2004-04-10 devnull .BI "fn " name
522 cfa37a7b 2004-04-10 devnull The first form defines a function with the given
523 cfa37a7b 2004-04-10 devnull .IR name .
524 cfa37a7b 2004-04-10 devnull Subsequently, whenever a command whose first argument is
526 cfa37a7b 2004-04-10 devnull is encountered, the current value of
527 cfa37a7b 2004-04-10 devnull the remainder of the command's argument list will be assigned to
528 cfa37a7b 2004-04-10 devnull .BR $* ,
529 cfa37a7b 2004-04-10 devnull after saving its current value, and
531 cfa37a7b 2004-04-10 devnull will execute the
532 cfa37a7b 2004-04-10 devnull .IR list .
533 cfa37a7b 2004-04-10 devnull The second form removes
534 cfa37a7b 2004-04-10 devnull .IR name 's
535 cfa37a7b 2004-04-10 devnull function definition.
537 cfa37a7b 2004-04-10 devnull .BI "fn " note { list }
540 cfa37a7b 2004-04-10 devnull .BI "fn " note
542 cfa37a7b 2004-04-10 devnull A function with a special name will be called when
544 cfa37a7b 2004-04-10 devnull receives a corresponding note; see
545 058b0118 2005-01-03 devnull .IR notify (3).
546 cfa37a7b 2004-04-10 devnull The valid note names (and corresponding notes) are
547 cfa37a7b 2004-04-10 devnull .B sighup
548 cfa37a7b 2004-04-10 devnull .RB ( hangup ),
549 cfa37a7b 2004-04-10 devnull .B sigint
550 cfa37a7b 2004-04-10 devnull .RB ( interrupt ),
551 cfa37a7b 2004-04-10 devnull .BR sigalrm
552 cfa37a7b 2004-04-10 devnull .RB ( alarm ),
554 cfa37a7b 2004-04-10 devnull .B sigfpe
555 cfa37a7b 2004-04-10 devnull (floating point trap).
556 cfa37a7b 2004-04-10 devnull By default
558 cfa37a7b 2004-04-10 devnull exits on receiving any signal, except when run interactively,
559 cfa37a7b 2004-04-10 devnull in which case interrupts and quits normally cause
561 cfa37a7b 2004-04-10 devnull to stop whatever it's doing and start reading a new command.
562 cfa37a7b 2004-04-10 devnull The second form causes
564 cfa37a7b 2004-04-10 devnull to handle a signal in the default manner.
566 cfa37a7b 2004-04-10 devnull recognizes an artificial note,
567 cfa37a7b 2004-04-10 devnull .BR sigexit ,
568 cfa37a7b 2004-04-10 devnull which occurs when
570 cfa37a7b 2004-04-10 devnull is about to finish executing.
572 cfa37a7b 2004-04-10 devnull .IB name = "argument command"
574 cfa37a7b 2004-04-10 devnull Any command may be preceded by a sequence of assignments
575 cfa37a7b 2004-04-10 devnull interspersed with redirections.
576 cfa37a7b 2004-04-10 devnull The assignments remain in effect until the end of the command, unless
577 cfa37a7b 2004-04-10 devnull the command is empty (i.e. the assignments stand alone), in which case
578 cfa37a7b 2004-04-10 devnull they are effective until rescinded by later assignments.
580 cfa37a7b 2004-04-10 devnull .SS Built-in Commands
581 cfa37a7b 2004-04-10 devnull These commands are executed internally by
582 cfa37a7b 2004-04-10 devnull .IR rc ,
583 cfa37a7b 2004-04-10 devnull usually because their execution changes or depends on
584 cfa37a7b 2004-04-10 devnull .IR rc 's
585 cfa37a7b 2004-04-10 devnull internal state.
588 cfa37a7b 2004-04-10 devnull .BI . " file ..."
590 cfa37a7b 2004-04-10 devnull Execute commands from
591 cfa37a7b 2004-04-10 devnull .IR file .
593 cfa37a7b 2004-04-10 devnull is set for the duration to the remainder of the argument list following
594 cfa37a7b 2004-04-10 devnull .IR file .
596 cfa37a7b 2004-04-10 devnull is searched for using
597 cfa37a7b 2004-04-10 devnull .BR $path .
599 cfa37a7b 2004-04-10 devnull .BI builtin " command ..."
602 cfa37a7b 2004-04-10 devnull .I command
603 cfa37a7b 2004-04-10 devnull as usual except that any function named
604 cfa37a7b 2004-04-10 devnull .I command
605 cfa37a7b 2004-04-10 devnull is ignored in favor of the built-in meaning.
607 cfa37a7b 2004-04-10 devnull .BI "cd [" dir "]"
609 cfa37a7b 2004-04-10 devnull Change the current directory to
610 cfa37a7b 2004-04-10 devnull .IR dir .
611 cfa37a7b 2004-04-10 devnull The default argument is
612 cfa37a7b 2004-04-10 devnull .BR $home .
614 cfa37a7b 2004-04-10 devnull is searched for in each of the directories mentioned in
615 cfa37a7b 2004-04-10 devnull .BR $cdpath .
617 cfa37a7b 2004-04-10 devnull .BI "eval [" "arg ..." "]"
619 cfa37a7b 2004-04-10 devnull The arguments are concatenated separated by spaces into a single string,
620 cfa37a7b 2004-04-10 devnull read as input to
621 cfa37a7b 2004-04-10 devnull .IR rc ,
622 cfa37a7b 2004-04-10 devnull and executed.
624 cfa37a7b 2004-04-10 devnull .BI "exec [" "command ..." "]"
626 cfa37a7b 2004-04-10 devnull This instance of
628 cfa37a7b 2004-04-10 devnull replaces itself with the given (non-built-in)
629 cfa37a7b 2004-04-10 devnull .IR command .
631 cfa37a7b 2004-04-10 devnull .BI "flag " f " [+-]"
633 cfa37a7b 2004-04-10 devnull Either set
634 cfa37a7b 2004-04-10 devnull .RB ( + ),
636 cfa37a7b 2004-04-10 devnull .RB ( - ),
637 cfa37a7b 2004-04-10 devnull or test (neither
641 cfa37a7b 2004-04-10 devnull the flag
645 cfa37a7b 2004-04-10 devnull is a single character, one of the command line flags (see Invocation, below).
647 cfa37a7b 2004-04-10 devnull .BI "exit [" status "]"
649 cfa37a7b 2004-04-10 devnull Exit with the given exit status.
650 cfa37a7b 2004-04-10 devnull If none is given, the current value of
651 cfa37a7b 2004-04-10 devnull .B $status
652 cfa37a7b 2004-04-10 devnull is used.
654 cfa37a7b 2004-04-10 devnull .BR "rfork " [ nNeEsfFm ]
656 cfa37a7b 2004-04-10 devnull Become a new process group using
657 cfa37a7b 2004-04-10 devnull .BI rfork( flags )
659 cfa37a7b 2004-04-10 devnull .I flags
660 cfa37a7b 2004-04-10 devnull is composed of the bitwise OR of the
661 cfa37a7b 2004-04-10 devnull .B rfork
662 cfa37a7b 2004-04-10 devnull flags specified by the option letters
664 cfa37a7b 2004-04-10 devnull .IR fork (2)).
666 cfa37a7b 2004-04-10 devnull .I flags
667 cfa37a7b 2004-04-10 devnull are given, they default to
668 cfa37a7b 2004-04-10 devnull .BR ens .
670 cfa37a7b 2004-04-10 devnull .I flags
671 cfa37a7b 2004-04-10 devnull and their meanings are:
674 cfa37a7b 2004-04-10 devnull .BR RFNAMEG ;
677 cfa37a7b 2004-04-10 devnull .BR RFCNAMEG ;
680 cfa37a7b 2004-04-10 devnull .BR RFENVG ;
683 cfa37a7b 2004-04-10 devnull .BR RFCENVG ;
686 cfa37a7b 2004-04-10 devnull .BR RFNOTEG ;
689 cfa37a7b 2004-04-10 devnull .BR RFFDG ;
692 cfa37a7b 2004-04-10 devnull .BR RFCFDG ;
696 cfa37a7b 2004-04-10 devnull .BR RFNOMNT .
698 cfa37a7b 2004-04-10 devnull .BI "shift [" n "]"
700 cfa37a7b 2004-04-10 devnull Delete the first
702 cfa37a7b 2004-04-10 devnull (default 1)
703 cfa37a7b 2004-04-10 devnull elements of
704 cfa37a7b 2004-04-10 devnull .BR $* .
706 cfa37a7b 2004-04-10 devnull .BI "wait [" pid "]"
708 cfa37a7b 2004-04-10 devnull Wait for the process with the given
710 cfa37a7b 2004-04-10 devnull to exit.
713 cfa37a7b 2004-04-10 devnull is given, all outstanding processes are waited for.
715 cfa37a7b 2004-04-10 devnull .BI whatis " name ..."
717 cfa37a7b 2004-04-10 devnull Print the value of each
719 cfa37a7b 2004-04-10 devnull in a form suitable for input to
720 cfa37a7b 2004-04-10 devnull .IR rc .
721 cfa37a7b 2004-04-10 devnull The output is
722 cfa37a7b 2004-04-10 devnull an assignment to any variable,
723 cfa37a7b 2004-04-10 devnull the definition of any function,
724 cfa37a7b 2004-04-10 devnull a call to
725 cfa37a7b 2004-04-10 devnull .B builtin
726 cfa37a7b 2004-04-10 devnull for any built-in command, or
727 cfa37a7b 2004-04-10 devnull the completed pathname of any executable file.
729 cfa37a7b 2004-04-10 devnull .BI ~ " subject pattern ..."
732 cfa37a7b 2004-04-10 devnull .I subject
733 cfa37a7b 2004-04-10 devnull is matched against each
734 cfa37a7b 2004-04-10 devnull .I pattern
735 cfa37a7b 2004-04-10 devnull in sequence.
736 cfa37a7b 2004-04-10 devnull If it matches any pattern,
737 cfa37a7b 2004-04-10 devnull .B $status
738 cfa37a7b 2004-04-10 devnull is set to zero.
739 cfa37a7b 2004-04-10 devnull Otherwise,
740 cfa37a7b 2004-04-10 devnull .B $status
741 cfa37a7b 2004-04-10 devnull is set to one.
742 cfa37a7b 2004-04-10 devnull Patterns are the same as for file name matching, except that
744 cfa37a7b 2004-04-10 devnull and the first character of
748 cfa37a7b 2004-04-10 devnull need not be matched explicitly.
750 cfa37a7b 2004-04-10 devnull .I patterns
751 cfa37a7b 2004-04-10 devnull are not subjected to
752 cfa37a7b 2004-04-10 devnull file name matching before the
754 cfa37a7b 2004-04-10 devnull command is executed, so they need not be enclosed in quotation marks.
756 cfa37a7b 2004-04-10 devnull .SS Environment
758 cfa37a7b 2004-04-10 devnull .I environment
759 cfa37a7b 2004-04-10 devnull is a list of strings made available to executing binaries by the
762 cfa37a7b 2004-04-10 devnull creates an environment entry for each variable whose value is non-empty,
763 cfa37a7b 2004-04-10 devnull and for each function.
764 cfa37a7b 2004-04-10 devnull The string for a variable entry has the variable's name followed by
766 cfa37a7b 2004-04-10 devnull and its value.
767 cfa37a7b 2004-04-10 devnull If the value has more than one component, these
768 c8b6342d 2005-01-13 devnull are separated by SOH (001)
769 cfa37a7b 2004-04-10 devnull characters.
770 cfa37a7b 2004-04-10 devnull The string for a function is just the
772 cfa37a7b 2004-04-10 devnull input that defines the function.
773 cfa37a7b 2004-04-10 devnull The name of a function in the environment is the function name
774 cfa37a7b 2004-04-10 devnull preceded by
775 cfa37a7b 2004-04-10 devnull .LR fn# .
779 cfa37a7b 2004-04-10 devnull starts executing it reads variable and function definitions from its
780 cfa37a7b 2004-04-10 devnull environment.
781 cfa37a7b 2004-04-10 devnull .SS Special Variables
782 cfa37a7b 2004-04-10 devnull The following variables are set or used by
783 cfa37a7b 2004-04-10 devnull .IR rc .
785 cfa37a7b 2004-04-10 devnull .TP \w'\fL$promptXX'u
788 cfa37a7b 2004-04-10 devnull .IR rc 's
789 cfa37a7b 2004-04-10 devnull argument list during initialization.
790 cfa37a7b 2004-04-10 devnull Whenever a
792 cfa37a7b 2004-04-10 devnull command or a function is executed, the current value is saved and
794 cfa37a7b 2004-04-10 devnull receives the new argument list.
795 cfa37a7b 2004-04-10 devnull The saved value is restored on completion of the
797 cfa37a7b 2004-04-10 devnull or function.
799 cfa37a7b 2004-04-10 devnull .B $apid
800 cfa37a7b 2004-04-10 devnull Whenever a process is started asynchronously with
802 cfa37a7b 2004-04-10 devnull .B $apid
803 cfa37a7b 2004-04-10 devnull is set to its process id.
805 cfa37a7b 2004-04-10 devnull .B $home
806 cfa37a7b 2004-04-10 devnull The default directory for
807 cfa37a7b 2004-04-10 devnull .BR cd .
810 cfa37a7b 2004-04-10 devnull The input field separators used in backquote substitutions.
813 cfa37a7b 2004-04-10 devnull is not set in
814 cfa37a7b 2004-04-10 devnull .IR rc 's
815 cfa37a7b 2004-04-10 devnull environment, it is initialized to blank, tab and newline.
817 cfa37a7b 2004-04-10 devnull .B $path
818 cfa37a7b 2004-04-10 devnull The search path used to find commands and input files
821 cfa37a7b 2004-04-10 devnull command.
822 cfa37a7b 2004-04-10 devnull If not set in the environment, it is initialized by
823 058b0118 2005-01-03 devnull parsing the
824 058b0118 2005-01-03 devnull .B $PATH
825 058b0118 2005-01-03 devnull variable
827 058b0118 2005-01-03 devnull .IR sh (1))
829 cfa37a7b 2004-04-10 devnull .BR "path=(.\ /bin)" .
830 058b0118 2005-01-03 devnull The variables
831 058b0118 2005-01-03 devnull .B $path
833 058b0118 2005-01-03 devnull .B $PATH
834 058b0118 2005-01-03 devnull are maintained together: changes to one will be reflected in the other.
835 058b0118 2005-01-03 devnull .\" Its use is discouraged; instead use
836 058b0118 2005-01-03 devnull .\" .IR bind (1)
837 058b0118 2005-01-03 devnull .\" to build a
838 058b0118 2005-01-03 devnull .\" .B /bin
839 058b0118 2005-01-03 devnull .\" containing what's needed.
842 cfa37a7b 2004-04-10 devnull Set during initialization to
843 cfa37a7b 2004-04-10 devnull .IR rc 's
844 cfa37a7b 2004-04-10 devnull process id.
846 cfa37a7b 2004-04-10 devnull .B $prompt
849 cfa37a7b 2004-04-10 devnull is run interactively, the first component of
850 cfa37a7b 2004-04-10 devnull .B $prompt
851 cfa37a7b 2004-04-10 devnull is printed before reading each command.
852 cfa37a7b 2004-04-10 devnull The second component is printed whenever a newline is typed and more lines
853 cfa37a7b 2004-04-10 devnull are required to complete the command.
854 cfa37a7b 2004-04-10 devnull If not set in the environment, it is initialized by
855 cfa37a7b 2004-04-10 devnull .BR "prompt=('%\ '\ '\ ')" .
857 cfa37a7b 2004-04-10 devnull .B $status
858 cfa37a7b 2004-04-10 devnull Set to the wait message of the last-executed program.
859 cfa37a7b 2004-04-10 devnull (unless started with
864 cfa37a7b 2004-04-10 devnull also change
865 cfa37a7b 2004-04-10 devnull .BR $status .
866 cfa37a7b 2004-04-10 devnull Its value is used to control execution in
867 cfa37a7b 2004-04-10 devnull .BR && ,
868 cfa37a7b 2004-04-10 devnull .BR || ,
871 cfa37a7b 2004-04-10 devnull .B while
872 cfa37a7b 2004-04-10 devnull commands.
875 cfa37a7b 2004-04-10 devnull exits at end-of-file of its input or on executing an
877 cfa37a7b 2004-04-10 devnull command with no argument,
878 cfa37a7b 2004-04-10 devnull .B $status
879 cfa37a7b 2004-04-10 devnull is its exit status.
881 cfa37a7b 2004-04-10 devnull .SS Invocation
884 cfa37a7b 2004-04-10 devnull is started with no arguments it reads commands from standard input.
885 cfa37a7b 2004-04-10 devnull Otherwise its first non-flag argument is the name of a file from which
886 cfa37a7b 2004-04-10 devnull to read commands (but see
889 cfa37a7b 2004-04-10 devnull Subsequent arguments become the initial value of
890 cfa37a7b 2004-04-10 devnull .BR $* .
892 cfa37a7b 2004-04-10 devnull accepts the following command-line flags.
894 cfa37a7b 2004-04-10 devnull .TP \w'\fL-c\ \fIstring\fLXX'u
895 cfa37a7b 2004-04-10 devnull .BI -c " string"
896 cfa37a7b 2004-04-10 devnull Commands are read from
897 cfa37a7b 2004-04-10 devnull .IR string .
900 cfa37a7b 2004-04-10 devnull Print out exit status after any command where the status is non-null.
904 cfa37a7b 2004-04-10 devnull .B $status
905 cfa37a7b 2004-04-10 devnull is non-null after executing a simple command.
910 cfa37a7b 2004-04-10 devnull is present, or
912 cfa37a7b 2004-04-10 devnull is given no arguments and its standard input is a terminal,
913 cfa37a7b 2004-04-10 devnull it runs interactively.
914 cfa37a7b 2004-04-10 devnull Commands are prompted for using
915 cfa37a7b 2004-04-10 devnull .BR $prompt .
918 cfa37a7b 2004-04-10 devnull Makes sure
920 cfa37a7b 2004-04-10 devnull is not run interactively.
925 cfa37a7b 2004-04-10 devnull is given or the first character of argument zero is
928 cfa37a7b 2004-04-10 devnull reads commands from
929 cfa37a7b 2004-04-10 devnull .BR $home/lib/profile ,
930 cfa37a7b 2004-04-10 devnull if it exists, before reading its normal input.
933 cfa37a7b 2004-04-10 devnull A no-op.
936 cfa37a7b 2004-04-10 devnull A no-op.
939 cfa37a7b 2004-04-10 devnull Echo input on file descriptor 2 as it is read.
942 cfa37a7b 2004-04-10 devnull Print each simple command before executing it.
945 cfa37a7b 2004-04-10 devnull Print debugging information (internal form of commands
946 cfa37a7b 2004-04-10 devnull as they are executed).
948 cfa37a7b 2004-04-10 devnull .SH SOURCE
949 c3674de4 2005-01-11 devnull .B \*9/src/cmd/rc
950 cfa37a7b 2004-04-10 devnull .SH "SEE ALSO"
951 cfa37a7b 2004-04-10 devnull Tom Duff,
952 cfa37a7b 2004-04-10 devnull ``Rc \- The Plan 9 Shell''.
953 cfa37a7b 2004-04-10 devnull .SH BUGS
954 cfa37a7b 2004-04-10 devnull There should be a way to match patterns against whole lists rather than
955 cfa37a7b 2004-04-10 devnull just single strings.
959 cfa37a7b 2004-04-10 devnull to check the value of
960 cfa37a7b 2004-04-10 devnull .B $status
962 cfa37a7b 2004-04-10 devnull .BR $status .
964 11c751cf 2005-01-07 devnull Functions that use here documents don't work.
966 cfa37a7b 2004-04-10 devnull Free carets don't get inserted next to keywords.
969 11c751cf 2005-01-07 devnull .BI <{ command }
970 11c751cf 2005-01-07 devnull syntax depends on the underlying operating system
971 11c751cf 2005-01-07 devnull providing a file descriptor device tree at
972 11c751cf 2005-01-07 devnull .BR /dev/fd .
974 11c751cf 2005-01-07 devnull By default, FreeBSD 5
975 11c751cf 2005-01-07 devnull does not provide file descriptors greater than 2
977 11c751cf 2005-01-07 devnull .BR /dev/fd .
978 11c751cf 2005-01-07 devnull To fix this, add
981 11c751cf 2005-01-07 devnull /fdescfs /dev/fd fdescfs rw 0 0
985 11c751cf 2005-01-07 devnull .BR /etc/fstab ,
986 11c751cf 2005-01-07 devnull and then
987 11c751cf 2005-01-07 devnull .B mount
988 11c751cf 2005-01-07 devnull .BR /dev/fd .
989 11c751cf 2005-01-07 devnull (Adding the line to
990 11c751cf 2005-01-07 devnull .B fstab
991 11c751cf 2005-01-07 devnull ensures causes FreeBSD to mount the file system
992 11c751cf 2005-01-07 devnull automatically at boot time.)
