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 94e1f2a4 2008-07-20 rsc Subscripts can also take the form
215 94e1f2a4 2008-07-20 rsc to indicate a sequence of elements.
216 cfa37a7b 2004-04-10 devnull Assignments to variables are described below.
218 cfa37a7b 2004-04-10 devnull .BI $# argument
220 cfa37a7b 2004-04-10 devnull The value is the number of elements in the named variable.
221 cfa37a7b 2004-04-10 devnull A variable
222 cfa37a7b 2004-04-10 devnull never assigned a value has zero elements.
225 cfa37a7b 2004-04-10 devnull .I argument
227 cfa37a7b 2004-04-10 devnull The value is a single string containing the components of the named variable
228 cfa37a7b 2004-04-10 devnull separated by spaces. A variable with zero elements yields the empty string.
230 cfa37a7b 2004-04-10 devnull .BI `{ command }
233 cfa37a7b 2004-04-10 devnull executes the
234 cfa37a7b 2004-04-10 devnull .I command
235 cfa37a7b 2004-04-10 devnull and reads its standard output, splitting it into a list of arguments,
236 cfa37a7b 2004-04-10 devnull using characters in
238 cfa37a7b 2004-04-10 devnull as separators.
241 cfa37a7b 2004-04-10 devnull is not otherwise set, its value is
242 cfa37a7b 2004-04-10 devnull .BR "'\ \et\en'" .
244 cfa37a7b 2004-04-10 devnull .BI <{ command }
246 cfa37a7b 2004-04-10 devnull .BI >{ command }
249 cfa37a7b 2004-04-10 devnull .I command
250 cfa37a7b 2004-04-10 devnull is executed asynchronously with its standard output or standard input
251 cfa37a7b 2004-04-10 devnull connected to a pipe.
252 cfa37a7b 2004-04-10 devnull The value of the argument is the name of a file
253 cfa37a7b 2004-04-10 devnull referring to the other end of the pipe.
254 cfa37a7b 2004-04-10 devnull This allows the construction of
255 cfa37a7b 2004-04-10 devnull non-linear pipelines.
256 cfa37a7b 2004-04-10 devnull For example, the following runs two commands
260 cfa37a7b 2004-04-10 devnull and uses
262 cfa37a7b 2004-04-10 devnull to compare their outputs
264 cfa37a7b 2004-04-10 devnull cmp <{old} <{new}
267 38b62735 2009-09-13 mt4swm .BI <>{ command }
270 38b62735 2009-09-13 mt4swm .I command
271 38b62735 2009-09-13 mt4swm is executed asynchronously with its standard input and
272 38b62735 2009-09-13 mt4swm output each connected to a pipe. The value of the argument
273 38b62735 2009-09-13 mt4swm is a pair of file names referring to the two other ends
274 38b62735 2009-09-13 mt4swm of the pipes, in the order corresponding to the symbols
278 38b62735 2009-09-13 mt4swm (first the pipe connected to the command's standard output,
279 38b62735 2009-09-13 mt4swm then the pipe connected to its standard input).
281 cfa37a7b 2004-04-10 devnull .IB argument ^ argument
285 cfa37a7b 2004-04-10 devnull operator concatenates its two operands.
286 cfa37a7b 2004-04-10 devnull If the two operands
287 cfa37a7b 2004-04-10 devnull have the same number of components, they are concatenated pairwise.
289 cfa37a7b 2004-04-10 devnull then one operand must have one component, and the other must be non-empty,
290 cfa37a7b 2004-04-10 devnull and concatenation is distributive.
292 cfa37a7b 2004-04-10 devnull .SS Free Carets
293 cfa37a7b 2004-04-10 devnull In most circumstances,
295 cfa37a7b 2004-04-10 devnull will insert the
297 cfa37a7b 2004-04-10 devnull operator automatically between words that are not separated by white space.
298 cfa37a7b 2004-04-10 devnull Whenever one of
302 cfa37a7b 2004-04-10 devnull follows a quoted or unquoted word or an unquoted word follows a quoted word
303 cfa37a7b 2004-04-10 devnull with no intervening blanks or tabs,
306 cfa37a7b 2004-04-10 devnull is inserted between the two.
307 cfa37a7b 2004-04-10 devnull If an unquoted word immediately follows a
309 cfa37a7b 2004-04-10 devnull and contains a character other than an alphanumeric, underscore,
314 cfa37a7b 2004-04-10 devnull is inserted before the first such character.
317 cfa37a7b 2004-04-10 devnull .B cc -$flags $stem.c
319 cfa37a7b 2004-04-10 devnull is equivalent to
321 cfa37a7b 2004-04-10 devnull .B cc -^$flags $stem^.c
322 cfa37a7b 2004-04-10 devnull .SS I/O Redirections
323 cfa37a7b 2004-04-10 devnull The sequence
324 cfa37a7b 2004-04-10 devnull .BI > file
325 cfa37a7b 2004-04-10 devnull redirects the standard output file (file descriptor 1, normally the
326 cfa37a7b 2004-04-10 devnull terminal) to the named
327 cfa37a7b 2004-04-10 devnull .IR file ;
328 cfa37a7b 2004-04-10 devnull .BI >> file
329 cfa37a7b 2004-04-10 devnull appends standard output to the file.
330 cfa37a7b 2004-04-10 devnull The standard input file (file descriptor 0, also normally the terminal)
331 cfa37a7b 2004-04-10 devnull may be redirected from a file by the sequence
332 cfa37a7b 2004-04-10 devnull .BI < file \f1,
333 cfa37a7b 2004-04-10 devnull or from an inline `here document'
334 cfa37a7b 2004-04-10 devnull by the sequence
335 cfa37a7b 2004-04-10 devnull .BI << eof-marker\f1.
336 cfa37a7b 2004-04-10 devnull The contents of a here document are lines of text taken from the command
337 cfa37a7b 2004-04-10 devnull input stream up to a line containing nothing but the
338 cfa37a7b 2004-04-10 devnull .IR eof-marker ,
339 cfa37a7b 2004-04-10 devnull which may be either a quoted or unquoted word.
341 cfa37a7b 2004-04-10 devnull .I eof-marker
342 cfa37a7b 2004-04-10 devnull is unquoted, variable names of the form
343 cfa37a7b 2004-04-10 devnull .BI $ word
344 cfa37a7b 2004-04-10 devnull have their values substituted from
346 cfa37a7b 2004-04-10 devnull environment.
348 cfa37a7b 2004-04-10 devnull .BI $ word
349 cfa37a7b 2004-04-10 devnull is followed by a caret
350 cfa37a7b 2004-04-10 devnull .RB ( ^ ),
351 cfa37a7b 2004-04-10 devnull the caret is deleted.
353 cfa37a7b 2004-04-10 devnull .I eof-marker
354 cfa37a7b 2004-04-10 devnull is quoted, no substitution occurs.
356 cfa37a7b 2004-04-10 devnull Redirections may be applied to a file-descriptor other than standard input
357 cfa37a7b 2004-04-10 devnull or output by qualifying the redirection operator
358 cfa37a7b 2004-04-10 devnull with a number in square brackets.
359 cfa37a7b 2004-04-10 devnull For example, the diagnostic output (file descriptor 2)
360 cfa37a7b 2004-04-10 devnull may be redirected by writing
361 cfa37a7b 2004-04-10 devnull .BR "cc junk.c >[2]junk" .
363 cfa37a7b 2004-04-10 devnull A file descriptor may be redirected to an already open descriptor by writing
364 cfa37a7b 2004-04-10 devnull .BI >[ fd0 = fd1 ]
366 cfa37a7b 2004-04-10 devnull .BI <[ fd0 = fd1 ]\f1.
368 cfa37a7b 2004-04-10 devnull is a previously opened file descriptor and
370 cfa37a7b 2004-04-10 devnull becomes a new copy (in the sense of
371 058b0118 2005-01-03 devnull .IR dup (3))
373 cfa37a7b 2004-04-10 devnull A file descriptor may be closed by writing
374 cfa37a7b 2004-04-10 devnull .BI >[ fd0 =]
376 cfa37a7b 2004-04-10 devnull .BI <[ fd0 =]\f1.
378 cfa37a7b 2004-04-10 devnull Redirections are executed from left to right.
379 cfa37a7b 2004-04-10 devnull Therefore,
380 cfa37a7b 2004-04-10 devnull .B cc junk.c >/dev/null >[2=1]
382 cfa37a7b 2004-04-10 devnull .B cc junk.c >[2=1] >/dev/null
383 cfa37a7b 2004-04-10 devnull have different effects: the first puts standard output in
384 cfa37a7b 2004-04-10 devnull .BR /dev/null
385 cfa37a7b 2004-04-10 devnull and then puts diagnostic output in the same place, where the second
386 cfa37a7b 2004-04-10 devnull directs diagnostic output to the terminal and sends standard output to
387 cfa37a7b 2004-04-10 devnull .BR /dev/null .
388 cfa37a7b 2004-04-10 devnull .SS Compound Commands
389 cfa37a7b 2004-04-10 devnull A pair of commands separated by a pipe operator
390 cfa37a7b 2004-04-10 devnull .RB ( | )
391 cfa37a7b 2004-04-10 devnull is a command.
392 cfa37a7b 2004-04-10 devnull The standard output of the left command is sent through a pipe
393 cfa37a7b 2004-04-10 devnull to the standard input of the right command.
394 cfa37a7b 2004-04-10 devnull The pipe operator may be decorated
395 cfa37a7b 2004-04-10 devnull to use different file descriptors.
396 cfa37a7b 2004-04-10 devnull .BI |[ fd ]
397 cfa37a7b 2004-04-10 devnull connects the output end of the pipe to file descriptor
399 cfa37a7b 2004-04-10 devnull rather than 1.
400 cfa37a7b 2004-04-10 devnull .BI |[ fd0 = fd1 ]
401 cfa37a7b 2004-04-10 devnull connects output to
403 cfa37a7b 2004-04-10 devnull of the left command and input to
405 cfa37a7b 2004-04-10 devnull of the right command.
407 cfa37a7b 2004-04-10 devnull A pair of commands separated by
411 cfa37a7b 2004-04-10 devnull is a command.
412 cfa37a7b 2004-04-10 devnull In either case, the left command is executed and its exit status examined.
413 cfa37a7b 2004-04-10 devnull If the operator is
415 cfa37a7b 2004-04-10 devnull the right command is executed if the left command's status is null.
417 cfa37a7b 2004-04-10 devnull causes the right command to be executed if the left command's status is non-null.
419 cfa37a7b 2004-04-10 devnull The exit status of a command may be inverted (non-null is changed to null, null
420 cfa37a7b 2004-04-10 devnull is changed to non-null) by preceding it with a
425 cfa37a7b 2004-04-10 devnull operator has highest precedence, and is left-associative (i.e. binds tighter
426 cfa37a7b 2004-04-10 devnull to the left than the right).
428 cfa37a7b 2004-04-10 devnull has intermediate precedence, and
432 cfa37a7b 2004-04-10 devnull have the lowest precedence.
434 cfa37a7b 2004-04-10 devnull The unary
436 cfa37a7b 2004-04-10 devnull operator, with precedence equal to
438 cfa37a7b 2004-04-10 devnull causes its operand to be executed in a subshell.
440 cfa37a7b 2004-04-10 devnull Each of the following is a command.
446 cfa37a7b 2004-04-10 devnull .I command
450 cfa37a7b 2004-04-10 devnull is a sequence of commands, separated by
453 cfa37a7b 2004-04-10 devnull or newline.
454 cfa37a7b 2004-04-10 devnull It is executed and
455 cfa37a7b 2004-04-10 devnull if its exit status is null, the
456 cfa37a7b 2004-04-10 devnull .I command
457 cfa37a7b 2004-04-10 devnull is executed.
459 cfa37a7b 2004-04-10 devnull .B if not
460 cfa37a7b 2004-04-10 devnull .I command
462 cfa37a7b 2004-04-10 devnull The immediately preceding command must have been
463 cfa37a7b 2004-04-10 devnull .BI if( list )
464 cfa37a7b 2004-04-10 devnull .IR command .
465 cfa37a7b 2004-04-10 devnull If its condition was non-zero, the
466 cfa37a7b 2004-04-10 devnull .I command
467 cfa37a7b 2004-04-10 devnull is executed.
469 cfa37a7b 2004-04-10 devnull .BI for( name
471 cfa37a7b 2004-04-10 devnull .IB arguments )
472 cfa37a7b 2004-04-10 devnull .I command
474 cfa37a7b 2004-04-10 devnull .BI for( name )
475 cfa37a7b 2004-04-10 devnull .I command
478 cfa37a7b 2004-04-10 devnull .I command
479 cfa37a7b 2004-04-10 devnull is executed once for each
480 cfa37a7b 2004-04-10 devnull .IR argument
481 cfa37a7b 2004-04-10 devnull with that argument assigned to
482 cfa37a7b 2004-04-10 devnull .IR name .
483 cfa37a7b 2004-04-10 devnull If the argument list is omitted,
485 cfa37a7b 2004-04-10 devnull is used.
487 cfa37a7b 2004-04-10 devnull .BI while( list )
488 cfa37a7b 2004-04-10 devnull .I command
492 cfa37a7b 2004-04-10 devnull is executed repeatedly until its exit status is non-null.
493 cfa37a7b 2004-04-10 devnull Each time it returns null status, the
494 cfa37a7b 2004-04-10 devnull .I command
495 cfa37a7b 2004-04-10 devnull is executed.
496 cfa37a7b 2004-04-10 devnull An empty
498 cfa37a7b 2004-04-10 devnull is taken to give null status.
500 cfa37a7b 2004-04-10 devnull .BI "switch(" argument "){" list }
503 cfa37a7b 2004-04-10 devnull .IR list
504 cfa37a7b 2004-04-10 devnull is searched for simple commands beginning with the word
505 cfa37a7b 2004-04-10 devnull .BR case .
506 cfa37a7b 2004-04-10 devnull (The search is only at the `top level' of the
507 cfa37a7b 2004-04-10 devnull .IR list .
508 cfa37a7b 2004-04-10 devnull That is,
509 cfa37a7b 2004-04-10 devnull .B cases
510 cfa37a7b 2004-04-10 devnull in nested constructs are not found.)
511 cfa37a7b 2004-04-10 devnull .I Argument
512 cfa37a7b 2004-04-10 devnull is matched against each word following
514 cfa37a7b 2004-04-10 devnull using the pattern-matching algorithm described above, except that
516 cfa37a7b 2004-04-10 devnull and the first characters of
520 cfa37a7b 2004-04-10 devnull need not be matched explicitly.
521 cfa37a7b 2004-04-10 devnull When a match is found, commands in the list are executed up to the next
522 cfa37a7b 2004-04-10 devnull following
524 cfa37a7b 2004-04-10 devnull command (at the top level) or the closing brace.
526 cfa37a7b 2004-04-10 devnull .BI { list }
528 cfa37a7b 2004-04-10 devnull Braces serve to alter the grouping of commands implied by operator
529 cfa37a7b 2004-04-10 devnull priorities.
532 cfa37a7b 2004-04-10 devnull is a sequence of commands separated by
535 cfa37a7b 2004-04-10 devnull or newline.
537 cfa37a7b 2004-04-10 devnull .BI "fn " name { list }
539 cfa37a7b 2004-04-10 devnull .BI "fn " name
541 cfa37a7b 2004-04-10 devnull The first form defines a function with the given
542 cfa37a7b 2004-04-10 devnull .IR name .
543 cfa37a7b 2004-04-10 devnull Subsequently, whenever a command whose first argument is
545 cfa37a7b 2004-04-10 devnull is encountered, the current value of
546 cfa37a7b 2004-04-10 devnull the remainder of the command's argument list will be assigned to
547 cfa37a7b 2004-04-10 devnull .BR $* ,
548 cfa37a7b 2004-04-10 devnull after saving its current value, and
550 cfa37a7b 2004-04-10 devnull will execute the
551 cfa37a7b 2004-04-10 devnull .IR list .
552 cfa37a7b 2004-04-10 devnull The second form removes
553 cfa37a7b 2004-04-10 devnull .IR name 's
554 cfa37a7b 2004-04-10 devnull function definition.
556 cfa37a7b 2004-04-10 devnull .BI "fn " note { list }
559 cfa37a7b 2004-04-10 devnull .BI "fn " note
561 cfa37a7b 2004-04-10 devnull A function with a special name will be called when
563 cfa37a7b 2004-04-10 devnull receives a corresponding note; see
564 058b0118 2005-01-03 devnull .IR notify (3).
565 cfa37a7b 2004-04-10 devnull The valid note names (and corresponding notes) are
566 cfa37a7b 2004-04-10 devnull .B sighup
567 cfa37a7b 2004-04-10 devnull .RB ( hangup ),
568 cfa37a7b 2004-04-10 devnull .B sigint
569 cfa37a7b 2004-04-10 devnull .RB ( interrupt ),
570 cfa37a7b 2004-04-10 devnull .BR sigalrm
571 cfa37a7b 2004-04-10 devnull .RB ( alarm ),
573 cfa37a7b 2004-04-10 devnull .B sigfpe
574 cfa37a7b 2004-04-10 devnull (floating point trap).
575 cfa37a7b 2004-04-10 devnull By default
577 cfa37a7b 2004-04-10 devnull exits on receiving any signal, except when run interactively,
578 cfa37a7b 2004-04-10 devnull in which case interrupts and quits normally cause
580 cfa37a7b 2004-04-10 devnull to stop whatever it's doing and start reading a new command.
581 cfa37a7b 2004-04-10 devnull The second form causes
583 cfa37a7b 2004-04-10 devnull to handle a signal in the default manner.
585 cfa37a7b 2004-04-10 devnull recognizes an artificial note,
586 cfa37a7b 2004-04-10 devnull .BR sigexit ,
587 cfa37a7b 2004-04-10 devnull which occurs when
589 cfa37a7b 2004-04-10 devnull is about to finish executing.
591 cfa37a7b 2004-04-10 devnull .IB name = "argument command"
593 cfa37a7b 2004-04-10 devnull Any command may be preceded by a sequence of assignments
594 cfa37a7b 2004-04-10 devnull interspersed with redirections.
595 cfa37a7b 2004-04-10 devnull The assignments remain in effect until the end of the command, unless
596 cfa37a7b 2004-04-10 devnull the command is empty (i.e. the assignments stand alone), in which case
597 cfa37a7b 2004-04-10 devnull they are effective until rescinded by later assignments.
599 cfa37a7b 2004-04-10 devnull .SS Built-in Commands
600 cfa37a7b 2004-04-10 devnull These commands are executed internally by
601 cfa37a7b 2004-04-10 devnull .IR rc ,
602 cfa37a7b 2004-04-10 devnull usually because their execution changes or depends on
603 cfa37a7b 2004-04-10 devnull .IR rc 's
604 cfa37a7b 2004-04-10 devnull internal state.
607 cfa37a7b 2004-04-10 devnull .BI . " file ..."
609 cfa37a7b 2004-04-10 devnull Execute commands from
610 cfa37a7b 2004-04-10 devnull .IR file .
612 cfa37a7b 2004-04-10 devnull is set for the duration to the remainder of the argument list following
613 cfa37a7b 2004-04-10 devnull .IR file .
615 cfa37a7b 2004-04-10 devnull is searched for using
616 cfa37a7b 2004-04-10 devnull .BR $path .
618 cfa37a7b 2004-04-10 devnull .BI builtin " command ..."
621 cfa37a7b 2004-04-10 devnull .I command
622 cfa37a7b 2004-04-10 devnull as usual except that any function named
623 cfa37a7b 2004-04-10 devnull .I command
624 cfa37a7b 2004-04-10 devnull is ignored in favor of the built-in meaning.
626 cfa37a7b 2004-04-10 devnull .BI "cd [" dir "]"
628 cfa37a7b 2004-04-10 devnull Change the current directory to
629 cfa37a7b 2004-04-10 devnull .IR dir .
630 cfa37a7b 2004-04-10 devnull The default argument is
631 cfa37a7b 2004-04-10 devnull .BR $home .
633 cfa37a7b 2004-04-10 devnull is searched for in each of the directories mentioned in
634 cfa37a7b 2004-04-10 devnull .BR $cdpath .
636 cfa37a7b 2004-04-10 devnull .BI "eval [" "arg ..." "]"
638 cfa37a7b 2004-04-10 devnull The arguments are concatenated separated by spaces into a single string,
639 cfa37a7b 2004-04-10 devnull read as input to
640 cfa37a7b 2004-04-10 devnull .IR rc ,
641 cfa37a7b 2004-04-10 devnull and executed.
643 cfa37a7b 2004-04-10 devnull .BI "exec [" "command ..." "]"
645 cfa37a7b 2004-04-10 devnull This instance of
647 cfa37a7b 2004-04-10 devnull replaces itself with the given (non-built-in)
648 cfa37a7b 2004-04-10 devnull .IR command .
650 cfa37a7b 2004-04-10 devnull .BI "flag " f " [+-]"
652 cfa37a7b 2004-04-10 devnull Either set
653 cfa37a7b 2004-04-10 devnull .RB ( + ),
655 cfa37a7b 2004-04-10 devnull .RB ( - ),
656 cfa37a7b 2004-04-10 devnull or test (neither
660 cfa37a7b 2004-04-10 devnull the flag
664 cfa37a7b 2004-04-10 devnull is a single character, one of the command line flags (see Invocation, below).
666 cfa37a7b 2004-04-10 devnull .BI "exit [" status "]"
668 cfa37a7b 2004-04-10 devnull Exit with the given exit status.
669 cfa37a7b 2004-04-10 devnull If none is given, the current value of
670 cfa37a7b 2004-04-10 devnull .B $status
671 cfa37a7b 2004-04-10 devnull is used.
673 cfa37a7b 2004-04-10 devnull .BR "rfork " [ nNeEsfFm ]
675 cfa37a7b 2004-04-10 devnull Become a new process group using
676 cfa37a7b 2004-04-10 devnull .BI rfork( flags )
678 cfa37a7b 2004-04-10 devnull .I flags
679 cfa37a7b 2004-04-10 devnull is composed of the bitwise OR of the
680 cfa37a7b 2004-04-10 devnull .B rfork
681 cfa37a7b 2004-04-10 devnull flags specified by the option letters
683 cfa37a7b 2004-04-10 devnull .IR fork (2)).
685 cfa37a7b 2004-04-10 devnull .I flags
686 cfa37a7b 2004-04-10 devnull are given, they default to
687 cfa37a7b 2004-04-10 devnull .BR ens .
689 cfa37a7b 2004-04-10 devnull .I flags
690 cfa37a7b 2004-04-10 devnull and their meanings are:
693 cfa37a7b 2004-04-10 devnull .BR RFNAMEG ;
696 cfa37a7b 2004-04-10 devnull .BR RFCNAMEG ;
699 cfa37a7b 2004-04-10 devnull .BR RFENVG ;
702 cfa37a7b 2004-04-10 devnull .BR RFCENVG ;
705 cfa37a7b 2004-04-10 devnull .BR RFNOTEG ;
708 cfa37a7b 2004-04-10 devnull .BR RFFDG ;
711 cfa37a7b 2004-04-10 devnull .BR RFCFDG ;
715 cfa37a7b 2004-04-10 devnull .BR RFNOMNT .
717 cfa37a7b 2004-04-10 devnull .BI "shift [" n "]"
719 cfa37a7b 2004-04-10 devnull Delete the first
721 cfa37a7b 2004-04-10 devnull (default 1)
722 cfa37a7b 2004-04-10 devnull elements of
723 cfa37a7b 2004-04-10 devnull .BR $* .
725 cfa37a7b 2004-04-10 devnull .BI "wait [" pid "]"
727 cfa37a7b 2004-04-10 devnull Wait for the process with the given
729 cfa37a7b 2004-04-10 devnull to exit.
732 cfa37a7b 2004-04-10 devnull is given, all outstanding processes are waited for.
734 cfa37a7b 2004-04-10 devnull .BI whatis " name ..."
736 cfa37a7b 2004-04-10 devnull Print the value of each
738 cfa37a7b 2004-04-10 devnull in a form suitable for input to
739 cfa37a7b 2004-04-10 devnull .IR rc .
740 cfa37a7b 2004-04-10 devnull The output is
741 cfa37a7b 2004-04-10 devnull an assignment to any variable,
742 cfa37a7b 2004-04-10 devnull the definition of any function,
743 cfa37a7b 2004-04-10 devnull a call to
744 cfa37a7b 2004-04-10 devnull .B builtin
745 cfa37a7b 2004-04-10 devnull for any built-in command, or
746 cfa37a7b 2004-04-10 devnull the completed pathname of any executable file.
748 cfa37a7b 2004-04-10 devnull .BI ~ " subject pattern ..."
751 cfa37a7b 2004-04-10 devnull .I subject
752 cfa37a7b 2004-04-10 devnull is matched against each
753 cfa37a7b 2004-04-10 devnull .I pattern
754 cfa37a7b 2004-04-10 devnull in sequence.
755 cfa37a7b 2004-04-10 devnull If it matches any pattern,
756 cfa37a7b 2004-04-10 devnull .B $status
757 cfa37a7b 2004-04-10 devnull is set to zero.
758 cfa37a7b 2004-04-10 devnull Otherwise,
759 cfa37a7b 2004-04-10 devnull .B $status
760 cfa37a7b 2004-04-10 devnull is set to one.
761 cfa37a7b 2004-04-10 devnull Patterns are the same as for file name matching, except that
763 cfa37a7b 2004-04-10 devnull and the first character of
767 cfa37a7b 2004-04-10 devnull need not be matched explicitly.
769 cfa37a7b 2004-04-10 devnull .I patterns
770 cfa37a7b 2004-04-10 devnull are not subjected to
771 cfa37a7b 2004-04-10 devnull file name matching before the
773 cfa37a7b 2004-04-10 devnull command is executed, so they need not be enclosed in quotation marks.
775 cfa37a7b 2004-04-10 devnull .SS Environment
777 cfa37a7b 2004-04-10 devnull .I environment
778 cfa37a7b 2004-04-10 devnull is a list of strings made available to executing binaries by the
781 cfa37a7b 2004-04-10 devnull creates an environment entry for each variable whose value is non-empty,
782 cfa37a7b 2004-04-10 devnull and for each function.
783 cfa37a7b 2004-04-10 devnull The string for a variable entry has the variable's name followed by
785 cfa37a7b 2004-04-10 devnull and its value.
786 cfa37a7b 2004-04-10 devnull If the value has more than one component, these
787 c8b6342d 2005-01-13 devnull are separated by SOH (001)
788 cfa37a7b 2004-04-10 devnull characters.
789 cfa37a7b 2004-04-10 devnull The string for a function is just the
791 cfa37a7b 2004-04-10 devnull input that defines the function.
792 cfa37a7b 2004-04-10 devnull The name of a function in the environment is the function name
793 cfa37a7b 2004-04-10 devnull preceded by
794 cfa37a7b 2004-04-10 devnull .LR fn# .
798 cfa37a7b 2004-04-10 devnull starts executing it reads variable and function definitions from its
799 cfa37a7b 2004-04-10 devnull environment.
800 cfa37a7b 2004-04-10 devnull .SS Special Variables
801 cfa37a7b 2004-04-10 devnull The following variables are set or used by
802 cfa37a7b 2004-04-10 devnull .IR rc .
804 cfa37a7b 2004-04-10 devnull .TP \w'\fL$promptXX'u
807 cfa37a7b 2004-04-10 devnull .IR rc 's
808 cfa37a7b 2004-04-10 devnull argument list during initialization.
809 cfa37a7b 2004-04-10 devnull Whenever a
811 cfa37a7b 2004-04-10 devnull command or a function is executed, the current value is saved and
813 cfa37a7b 2004-04-10 devnull receives the new argument list.
814 cfa37a7b 2004-04-10 devnull The saved value is restored on completion of the
816 cfa37a7b 2004-04-10 devnull or function.
818 cfa37a7b 2004-04-10 devnull .B $apid
819 cfa37a7b 2004-04-10 devnull Whenever a process is started asynchronously with
821 cfa37a7b 2004-04-10 devnull .B $apid
822 cfa37a7b 2004-04-10 devnull is set to its process id.
824 cfa37a7b 2004-04-10 devnull .B $home
825 cfa37a7b 2004-04-10 devnull The default directory for
826 cfa37a7b 2004-04-10 devnull .BR cd .
829 cfa37a7b 2004-04-10 devnull The input field separators used in backquote substitutions.
832 cfa37a7b 2004-04-10 devnull is not set in
833 cfa37a7b 2004-04-10 devnull .IR rc 's
834 cfa37a7b 2004-04-10 devnull environment, it is initialized to blank, tab and newline.
836 cfa37a7b 2004-04-10 devnull .B $path
837 cfa37a7b 2004-04-10 devnull The search path used to find commands and input files
840 cfa37a7b 2004-04-10 devnull command.
841 cfa37a7b 2004-04-10 devnull If not set in the environment, it is initialized by
842 058b0118 2005-01-03 devnull parsing the
843 058b0118 2005-01-03 devnull .B $PATH
844 058b0118 2005-01-03 devnull variable
846 058b0118 2005-01-03 devnull .IR sh (1))
848 cfa37a7b 2004-04-10 devnull .BR "path=(.\ /bin)" .
849 058b0118 2005-01-03 devnull The variables
850 058b0118 2005-01-03 devnull .B $path
852 058b0118 2005-01-03 devnull .B $PATH
853 058b0118 2005-01-03 devnull are maintained together: changes to one will be reflected in the other.
854 058b0118 2005-01-03 devnull .\" Its use is discouraged; instead use
855 058b0118 2005-01-03 devnull .\" .IR bind (1)
856 058b0118 2005-01-03 devnull .\" to build a
857 058b0118 2005-01-03 devnull .\" .B /bin
858 058b0118 2005-01-03 devnull .\" containing what's needed.
861 cfa37a7b 2004-04-10 devnull Set during initialization to
862 cfa37a7b 2004-04-10 devnull .IR rc 's
863 cfa37a7b 2004-04-10 devnull process id.
865 cfa37a7b 2004-04-10 devnull .B $prompt
868 cfa37a7b 2004-04-10 devnull is run interactively, the first component of
869 cfa37a7b 2004-04-10 devnull .B $prompt
870 cfa37a7b 2004-04-10 devnull is printed before reading each command.
871 cfa37a7b 2004-04-10 devnull The second component is printed whenever a newline is typed and more lines
872 cfa37a7b 2004-04-10 devnull are required to complete the command.
873 cfa37a7b 2004-04-10 devnull If not set in the environment, it is initialized by
874 cfa37a7b 2004-04-10 devnull .BR "prompt=('%\ '\ '\ ')" .
876 cfa37a7b 2004-04-10 devnull .B $status
877 cfa37a7b 2004-04-10 devnull Set to the wait message of the last-executed program.
878 cfa37a7b 2004-04-10 devnull (unless started with
883 cfa37a7b 2004-04-10 devnull also change
884 cfa37a7b 2004-04-10 devnull .BR $status .
885 cfa37a7b 2004-04-10 devnull Its value is used to control execution in
886 cfa37a7b 2004-04-10 devnull .BR && ,
887 cfa37a7b 2004-04-10 devnull .BR || ,
890 cfa37a7b 2004-04-10 devnull .B while
891 cfa37a7b 2004-04-10 devnull commands.
894 cfa37a7b 2004-04-10 devnull exits at end-of-file of its input or on executing an
896 cfa37a7b 2004-04-10 devnull command with no argument,
897 cfa37a7b 2004-04-10 devnull .B $status
898 cfa37a7b 2004-04-10 devnull is its exit status.
900 cfa37a7b 2004-04-10 devnull .SS Invocation
903 cfa37a7b 2004-04-10 devnull is started with no arguments it reads commands from standard input.
904 cfa37a7b 2004-04-10 devnull Otherwise its first non-flag argument is the name of a file from which
905 cfa37a7b 2004-04-10 devnull to read commands (but see
908 cfa37a7b 2004-04-10 devnull Subsequent arguments become the initial value of
909 cfa37a7b 2004-04-10 devnull .BR $* .
911 cfa37a7b 2004-04-10 devnull accepts the following command-line flags.
913 cfa37a7b 2004-04-10 devnull .TP \w'\fL-c\ \fIstring\fLXX'u
914 cfa37a7b 2004-04-10 devnull .BI -c " string"
915 cfa37a7b 2004-04-10 devnull Commands are read from
916 cfa37a7b 2004-04-10 devnull .IR string .
919 cfa37a7b 2004-04-10 devnull Print out exit status after any command where the status is non-null.
923 cfa37a7b 2004-04-10 devnull .B $status
924 cfa37a7b 2004-04-10 devnull is non-null after executing a simple command.
929 cfa37a7b 2004-04-10 devnull is present, or
931 cfa37a7b 2004-04-10 devnull is given no arguments and its standard input is a terminal,
932 cfa37a7b 2004-04-10 devnull it runs interactively.
933 cfa37a7b 2004-04-10 devnull Commands are prompted for using
934 cfa37a7b 2004-04-10 devnull .BR $prompt .
937 cfa37a7b 2004-04-10 devnull Makes sure
939 cfa37a7b 2004-04-10 devnull is not run interactively.
944 cfa37a7b 2004-04-10 devnull is given or the first character of argument zero is
947 cfa37a7b 2004-04-10 devnull reads commands from
948 cfa37a7b 2004-04-10 devnull .BR $home/lib/profile ,
949 cfa37a7b 2004-04-10 devnull if it exists, before reading its normal input.
952 cfa37a7b 2004-04-10 devnull A no-op.
955 cfa37a7b 2004-04-10 devnull A no-op.
958 cfa37a7b 2004-04-10 devnull Echo input on file descriptor 2 as it is read.
961 cfa37a7b 2004-04-10 devnull Print each simple command before executing it.
964 cfa37a7b 2004-04-10 devnull Print debugging information (internal form of commands
965 cfa37a7b 2004-04-10 devnull as they are executed).
967 cfa37a7b 2004-04-10 devnull .SH SOURCE
968 c3674de4 2005-01-11 devnull .B \*9/src/cmd/rc
969 cfa37a7b 2004-04-10 devnull .SH "SEE ALSO"
970 cfa37a7b 2004-04-10 devnull Tom Duff,
971 cfa37a7b 2004-04-10 devnull ``Rc \- The Plan 9 Shell''.
972 cfa37a7b 2004-04-10 devnull .SH BUGS
973 cfa37a7b 2004-04-10 devnull There should be a way to match patterns against whole lists rather than
974 cfa37a7b 2004-04-10 devnull just single strings.
978 cfa37a7b 2004-04-10 devnull to check the value of
979 cfa37a7b 2004-04-10 devnull .B $status
981 cfa37a7b 2004-04-10 devnull .BR $status .
983 11c751cf 2005-01-07 devnull Functions that use here documents don't work.
985 cfa37a7b 2004-04-10 devnull Free carets don't get inserted next to keywords.
988 11c751cf 2005-01-07 devnull .BI <{ command }
989 11c751cf 2005-01-07 devnull syntax depends on the underlying operating system
990 11c751cf 2005-01-07 devnull providing a file descriptor device tree at
991 11c751cf 2005-01-07 devnull .BR /dev/fd .
993 519fe613 2011-10-31 rsc Some FreeBSD installations
994 11c751cf 2005-01-07 devnull does not provide file descriptors greater than 2
996 11c751cf 2005-01-07 devnull .BR /dev/fd .
997 11c751cf 2005-01-07 devnull To fix this, add
1000 11c751cf 2005-01-07 devnull /fdescfs /dev/fd fdescfs rw 0 0
1004 11c751cf 2005-01-07 devnull .BR /etc/fstab ,
1005 11c751cf 2005-01-07 devnull and then
1006 11c751cf 2005-01-07 devnull .B mount
1007 11c751cf 2005-01-07 devnull .BR /dev/fd .
1008 11c751cf 2005-01-07 devnull (Adding the line to
1009 11c751cf 2005-01-07 devnull .B fstab
1010 11c751cf 2005-01-07 devnull ensures causes FreeBSD to mount the file system
1011 11c751cf 2005-01-07 devnull automatically at boot time.)
