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 cfa37a7b 2004-04-10 devnull .IB argument ^ argument
271 cfa37a7b 2004-04-10 devnull operator concatenates its two operands.
272 cfa37a7b 2004-04-10 devnull If the two operands
273 cfa37a7b 2004-04-10 devnull have the same number of components, they are concatenated pairwise.
275 cfa37a7b 2004-04-10 devnull then one operand must have one component, and the other must be non-empty,
276 cfa37a7b 2004-04-10 devnull and concatenation is distributive.
278 cfa37a7b 2004-04-10 devnull .SS Free Carets
279 cfa37a7b 2004-04-10 devnull In most circumstances,
281 cfa37a7b 2004-04-10 devnull will insert the
283 cfa37a7b 2004-04-10 devnull operator automatically between words that are not separated by white space.
284 cfa37a7b 2004-04-10 devnull Whenever one of
288 cfa37a7b 2004-04-10 devnull follows a quoted or unquoted word or an unquoted word follows a quoted word
289 cfa37a7b 2004-04-10 devnull with no intervening blanks or tabs,
292 cfa37a7b 2004-04-10 devnull is inserted between the two.
293 cfa37a7b 2004-04-10 devnull If an unquoted word immediately follows a
295 cfa37a7b 2004-04-10 devnull and contains a character other than an alphanumeric, underscore,
300 cfa37a7b 2004-04-10 devnull is inserted before the first such character.
303 cfa37a7b 2004-04-10 devnull .B cc -$flags $stem.c
305 cfa37a7b 2004-04-10 devnull is equivalent to
307 cfa37a7b 2004-04-10 devnull .B cc -^$flags $stem^.c
308 cfa37a7b 2004-04-10 devnull .SS I/O Redirections
309 cfa37a7b 2004-04-10 devnull The sequence
310 cfa37a7b 2004-04-10 devnull .BI > file
311 cfa37a7b 2004-04-10 devnull redirects the standard output file (file descriptor 1, normally the
312 cfa37a7b 2004-04-10 devnull terminal) to the named
313 cfa37a7b 2004-04-10 devnull .IR file ;
314 cfa37a7b 2004-04-10 devnull .BI >> file
315 cfa37a7b 2004-04-10 devnull appends standard output to the file.
316 cfa37a7b 2004-04-10 devnull The standard input file (file descriptor 0, also normally the terminal)
317 cfa37a7b 2004-04-10 devnull may be redirected from a file by the sequence
318 cfa37a7b 2004-04-10 devnull .BI < file \f1,
319 cfa37a7b 2004-04-10 devnull or from an inline `here document'
320 cfa37a7b 2004-04-10 devnull by the sequence
321 cfa37a7b 2004-04-10 devnull .BI << eof-marker\f1.
322 cfa37a7b 2004-04-10 devnull The contents of a here document are lines of text taken from the command
323 cfa37a7b 2004-04-10 devnull input stream up to a line containing nothing but the
324 cfa37a7b 2004-04-10 devnull .IR eof-marker ,
325 cfa37a7b 2004-04-10 devnull which may be either a quoted or unquoted word.
327 cfa37a7b 2004-04-10 devnull .I eof-marker
328 cfa37a7b 2004-04-10 devnull is unquoted, variable names of the form
329 cfa37a7b 2004-04-10 devnull .BI $ word
330 cfa37a7b 2004-04-10 devnull have their values substituted from
332 cfa37a7b 2004-04-10 devnull environment.
334 cfa37a7b 2004-04-10 devnull .BI $ word
335 cfa37a7b 2004-04-10 devnull is followed by a caret
336 cfa37a7b 2004-04-10 devnull .RB ( ^ ),
337 cfa37a7b 2004-04-10 devnull the caret is deleted.
339 cfa37a7b 2004-04-10 devnull .I eof-marker
340 cfa37a7b 2004-04-10 devnull is quoted, no substitution occurs.
342 cfa37a7b 2004-04-10 devnull Redirections may be applied to a file-descriptor other than standard input
343 cfa37a7b 2004-04-10 devnull or output by qualifying the redirection operator
344 cfa37a7b 2004-04-10 devnull with a number in square brackets.
345 cfa37a7b 2004-04-10 devnull For example, the diagnostic output (file descriptor 2)
346 cfa37a7b 2004-04-10 devnull may be redirected by writing
347 cfa37a7b 2004-04-10 devnull .BR "cc junk.c >[2]junk" .
349 cfa37a7b 2004-04-10 devnull A file descriptor may be redirected to an already open descriptor by writing
350 cfa37a7b 2004-04-10 devnull .BI >[ fd0 = fd1 ]
352 cfa37a7b 2004-04-10 devnull .BI <[ fd0 = fd1 ]\f1.
354 cfa37a7b 2004-04-10 devnull is a previously opened file descriptor and
356 cfa37a7b 2004-04-10 devnull becomes a new copy (in the sense of
357 058b0118 2005-01-03 devnull .IR dup (3))
359 cfa37a7b 2004-04-10 devnull A file descriptor may be closed by writing
360 cfa37a7b 2004-04-10 devnull .BI >[ fd0 =]
362 cfa37a7b 2004-04-10 devnull .BI <[ fd0 =]\f1.
364 cfa37a7b 2004-04-10 devnull Redirections are executed from left to right.
365 cfa37a7b 2004-04-10 devnull Therefore,
366 cfa37a7b 2004-04-10 devnull .B cc junk.c >/dev/null >[2=1]
368 cfa37a7b 2004-04-10 devnull .B cc junk.c >[2=1] >/dev/null
369 cfa37a7b 2004-04-10 devnull have different effects: the first puts standard output in
370 cfa37a7b 2004-04-10 devnull .BR /dev/null
371 cfa37a7b 2004-04-10 devnull and then puts diagnostic output in the same place, where the second
372 cfa37a7b 2004-04-10 devnull directs diagnostic output to the terminal and sends standard output to
373 cfa37a7b 2004-04-10 devnull .BR /dev/null .
374 cfa37a7b 2004-04-10 devnull .SS Compound Commands
375 cfa37a7b 2004-04-10 devnull A pair of commands separated by a pipe operator
376 cfa37a7b 2004-04-10 devnull .RB ( | )
377 cfa37a7b 2004-04-10 devnull is a command.
378 cfa37a7b 2004-04-10 devnull The standard output of the left command is sent through a pipe
379 cfa37a7b 2004-04-10 devnull to the standard input of the right command.
380 cfa37a7b 2004-04-10 devnull The pipe operator may be decorated
381 cfa37a7b 2004-04-10 devnull to use different file descriptors.
382 cfa37a7b 2004-04-10 devnull .BI |[ fd ]
383 cfa37a7b 2004-04-10 devnull connects the output end of the pipe to file descriptor
385 cfa37a7b 2004-04-10 devnull rather than 1.
386 cfa37a7b 2004-04-10 devnull .BI |[ fd0 = fd1 ]
387 cfa37a7b 2004-04-10 devnull connects output to
389 cfa37a7b 2004-04-10 devnull of the left command and input to
391 cfa37a7b 2004-04-10 devnull of the right command.
393 cfa37a7b 2004-04-10 devnull A pair of commands separated by
397 cfa37a7b 2004-04-10 devnull is a command.
398 cfa37a7b 2004-04-10 devnull In either case, the left command is executed and its exit status examined.
399 cfa37a7b 2004-04-10 devnull If the operator is
401 cfa37a7b 2004-04-10 devnull the right command is executed if the left command's status is null.
403 cfa37a7b 2004-04-10 devnull causes the right command to be executed if the left command's status is non-null.
405 cfa37a7b 2004-04-10 devnull The exit status of a command may be inverted (non-null is changed to null, null
406 cfa37a7b 2004-04-10 devnull is changed to non-null) by preceding it with a
411 cfa37a7b 2004-04-10 devnull operator has highest precedence, and is left-associative (i.e. binds tighter
412 cfa37a7b 2004-04-10 devnull to the left than the right).
414 cfa37a7b 2004-04-10 devnull has intermediate precedence, and
418 cfa37a7b 2004-04-10 devnull have the lowest precedence.
420 cfa37a7b 2004-04-10 devnull The unary
422 cfa37a7b 2004-04-10 devnull operator, with precedence equal to
424 cfa37a7b 2004-04-10 devnull causes its operand to be executed in a subshell.
426 cfa37a7b 2004-04-10 devnull Each of the following is a command.
432 cfa37a7b 2004-04-10 devnull .I command
436 cfa37a7b 2004-04-10 devnull is a sequence of commands, separated by
439 cfa37a7b 2004-04-10 devnull or newline.
440 cfa37a7b 2004-04-10 devnull It is executed and
441 cfa37a7b 2004-04-10 devnull if its exit status is null, the
442 cfa37a7b 2004-04-10 devnull .I command
443 cfa37a7b 2004-04-10 devnull is executed.
445 cfa37a7b 2004-04-10 devnull .B if not
446 cfa37a7b 2004-04-10 devnull .I command
448 cfa37a7b 2004-04-10 devnull The immediately preceding command must have been
449 cfa37a7b 2004-04-10 devnull .BI if( list )
450 cfa37a7b 2004-04-10 devnull .IR command .
451 cfa37a7b 2004-04-10 devnull If its condition was non-zero, the
452 cfa37a7b 2004-04-10 devnull .I command
453 cfa37a7b 2004-04-10 devnull is executed.
455 cfa37a7b 2004-04-10 devnull .BI for( name
457 cfa37a7b 2004-04-10 devnull .IB arguments )
458 cfa37a7b 2004-04-10 devnull .I command
460 cfa37a7b 2004-04-10 devnull .BI for( name )
461 cfa37a7b 2004-04-10 devnull .I command
464 cfa37a7b 2004-04-10 devnull .I command
465 cfa37a7b 2004-04-10 devnull is executed once for each
466 cfa37a7b 2004-04-10 devnull .IR argument
467 cfa37a7b 2004-04-10 devnull with that argument assigned to
468 cfa37a7b 2004-04-10 devnull .IR name .
469 cfa37a7b 2004-04-10 devnull If the argument list is omitted,
471 cfa37a7b 2004-04-10 devnull is used.
473 cfa37a7b 2004-04-10 devnull .BI while( list )
474 cfa37a7b 2004-04-10 devnull .I command
478 cfa37a7b 2004-04-10 devnull is executed repeatedly until its exit status is non-null.
479 cfa37a7b 2004-04-10 devnull Each time it returns null status, the
480 cfa37a7b 2004-04-10 devnull .I command
481 cfa37a7b 2004-04-10 devnull is executed.
482 cfa37a7b 2004-04-10 devnull An empty
484 cfa37a7b 2004-04-10 devnull is taken to give null status.
486 cfa37a7b 2004-04-10 devnull .BI "switch(" argument "){" list }
489 cfa37a7b 2004-04-10 devnull .IR list
490 cfa37a7b 2004-04-10 devnull is searched for simple commands beginning with the word
491 cfa37a7b 2004-04-10 devnull .BR case .
492 cfa37a7b 2004-04-10 devnull (The search is only at the `top level' of the
493 cfa37a7b 2004-04-10 devnull .IR list .
494 cfa37a7b 2004-04-10 devnull That is,
495 cfa37a7b 2004-04-10 devnull .B cases
496 cfa37a7b 2004-04-10 devnull in nested constructs are not found.)
497 cfa37a7b 2004-04-10 devnull .I Argument
498 cfa37a7b 2004-04-10 devnull is matched against each word following
500 cfa37a7b 2004-04-10 devnull using the pattern-matching algorithm described above, except that
502 cfa37a7b 2004-04-10 devnull and the first characters of
506 cfa37a7b 2004-04-10 devnull need not be matched explicitly.
507 cfa37a7b 2004-04-10 devnull When a match is found, commands in the list are executed up to the next
508 cfa37a7b 2004-04-10 devnull following
510 cfa37a7b 2004-04-10 devnull command (at the top level) or the closing brace.
512 cfa37a7b 2004-04-10 devnull .BI { list }
514 cfa37a7b 2004-04-10 devnull Braces serve to alter the grouping of commands implied by operator
515 cfa37a7b 2004-04-10 devnull priorities.
518 cfa37a7b 2004-04-10 devnull is a sequence of commands separated by
521 cfa37a7b 2004-04-10 devnull or newline.
523 cfa37a7b 2004-04-10 devnull .BI "fn " name { list }
525 cfa37a7b 2004-04-10 devnull .BI "fn " name
527 cfa37a7b 2004-04-10 devnull The first form defines a function with the given
528 cfa37a7b 2004-04-10 devnull .IR name .
529 cfa37a7b 2004-04-10 devnull Subsequently, whenever a command whose first argument is
531 cfa37a7b 2004-04-10 devnull is encountered, the current value of
532 cfa37a7b 2004-04-10 devnull the remainder of the command's argument list will be assigned to
533 cfa37a7b 2004-04-10 devnull .BR $* ,
534 cfa37a7b 2004-04-10 devnull after saving its current value, and
536 cfa37a7b 2004-04-10 devnull will execute the
537 cfa37a7b 2004-04-10 devnull .IR list .
538 cfa37a7b 2004-04-10 devnull The second form removes
539 cfa37a7b 2004-04-10 devnull .IR name 's
540 cfa37a7b 2004-04-10 devnull function definition.
542 cfa37a7b 2004-04-10 devnull .BI "fn " note { list }
545 cfa37a7b 2004-04-10 devnull .BI "fn " note
547 cfa37a7b 2004-04-10 devnull A function with a special name will be called when
549 cfa37a7b 2004-04-10 devnull receives a corresponding note; see
550 058b0118 2005-01-03 devnull .IR notify (3).
551 cfa37a7b 2004-04-10 devnull The valid note names (and corresponding notes) are
552 cfa37a7b 2004-04-10 devnull .B sighup
553 cfa37a7b 2004-04-10 devnull .RB ( hangup ),
554 cfa37a7b 2004-04-10 devnull .B sigint
555 cfa37a7b 2004-04-10 devnull .RB ( interrupt ),
556 cfa37a7b 2004-04-10 devnull .BR sigalrm
557 cfa37a7b 2004-04-10 devnull .RB ( alarm ),
559 cfa37a7b 2004-04-10 devnull .B sigfpe
560 cfa37a7b 2004-04-10 devnull (floating point trap).
561 cfa37a7b 2004-04-10 devnull By default
563 cfa37a7b 2004-04-10 devnull exits on receiving any signal, except when run interactively,
564 cfa37a7b 2004-04-10 devnull in which case interrupts and quits normally cause
566 cfa37a7b 2004-04-10 devnull to stop whatever it's doing and start reading a new command.
567 cfa37a7b 2004-04-10 devnull The second form causes
569 cfa37a7b 2004-04-10 devnull to handle a signal in the default manner.
571 cfa37a7b 2004-04-10 devnull recognizes an artificial note,
572 cfa37a7b 2004-04-10 devnull .BR sigexit ,
573 cfa37a7b 2004-04-10 devnull which occurs when
575 cfa37a7b 2004-04-10 devnull is about to finish executing.
577 cfa37a7b 2004-04-10 devnull .IB name = "argument command"
579 cfa37a7b 2004-04-10 devnull Any command may be preceded by a sequence of assignments
580 cfa37a7b 2004-04-10 devnull interspersed with redirections.
581 cfa37a7b 2004-04-10 devnull The assignments remain in effect until the end of the command, unless
582 cfa37a7b 2004-04-10 devnull the command is empty (i.e. the assignments stand alone), in which case
583 cfa37a7b 2004-04-10 devnull they are effective until rescinded by later assignments.
585 cfa37a7b 2004-04-10 devnull .SS Built-in Commands
586 cfa37a7b 2004-04-10 devnull These commands are executed internally by
587 cfa37a7b 2004-04-10 devnull .IR rc ,
588 cfa37a7b 2004-04-10 devnull usually because their execution changes or depends on
589 cfa37a7b 2004-04-10 devnull .IR rc 's
590 cfa37a7b 2004-04-10 devnull internal state.
593 cfa37a7b 2004-04-10 devnull .BI . " file ..."
595 cfa37a7b 2004-04-10 devnull Execute commands from
596 cfa37a7b 2004-04-10 devnull .IR file .
598 cfa37a7b 2004-04-10 devnull is set for the duration to the remainder of the argument list following
599 cfa37a7b 2004-04-10 devnull .IR file .
601 cfa37a7b 2004-04-10 devnull is searched for using
602 cfa37a7b 2004-04-10 devnull .BR $path .
604 cfa37a7b 2004-04-10 devnull .BI builtin " command ..."
607 cfa37a7b 2004-04-10 devnull .I command
608 cfa37a7b 2004-04-10 devnull as usual except that any function named
609 cfa37a7b 2004-04-10 devnull .I command
610 cfa37a7b 2004-04-10 devnull is ignored in favor of the built-in meaning.
612 cfa37a7b 2004-04-10 devnull .BI "cd [" dir "]"
614 cfa37a7b 2004-04-10 devnull Change the current directory to
615 cfa37a7b 2004-04-10 devnull .IR dir .
616 cfa37a7b 2004-04-10 devnull The default argument is
617 cfa37a7b 2004-04-10 devnull .BR $home .
619 cfa37a7b 2004-04-10 devnull is searched for in each of the directories mentioned in
620 cfa37a7b 2004-04-10 devnull .BR $cdpath .
622 cfa37a7b 2004-04-10 devnull .BI "eval [" "arg ..." "]"
624 cfa37a7b 2004-04-10 devnull The arguments are concatenated separated by spaces into a single string,
625 cfa37a7b 2004-04-10 devnull read as input to
626 cfa37a7b 2004-04-10 devnull .IR rc ,
627 cfa37a7b 2004-04-10 devnull and executed.
629 cfa37a7b 2004-04-10 devnull .BI "exec [" "command ..." "]"
631 cfa37a7b 2004-04-10 devnull This instance of
633 cfa37a7b 2004-04-10 devnull replaces itself with the given (non-built-in)
634 cfa37a7b 2004-04-10 devnull .IR command .
636 cfa37a7b 2004-04-10 devnull .BI "flag " f " [+-]"
638 cfa37a7b 2004-04-10 devnull Either set
639 cfa37a7b 2004-04-10 devnull .RB ( + ),
641 cfa37a7b 2004-04-10 devnull .RB ( - ),
642 cfa37a7b 2004-04-10 devnull or test (neither
646 cfa37a7b 2004-04-10 devnull the flag
650 cfa37a7b 2004-04-10 devnull is a single character, one of the command line flags (see Invocation, below).
652 cfa37a7b 2004-04-10 devnull .BI "exit [" status "]"
654 cfa37a7b 2004-04-10 devnull Exit with the given exit status.
655 cfa37a7b 2004-04-10 devnull If none is given, the current value of
656 cfa37a7b 2004-04-10 devnull .B $status
657 cfa37a7b 2004-04-10 devnull is used.
659 cfa37a7b 2004-04-10 devnull .BR "rfork " [ nNeEsfFm ]
661 cfa37a7b 2004-04-10 devnull Become a new process group using
662 cfa37a7b 2004-04-10 devnull .BI rfork( flags )
664 cfa37a7b 2004-04-10 devnull .I flags
665 cfa37a7b 2004-04-10 devnull is composed of the bitwise OR of the
666 cfa37a7b 2004-04-10 devnull .B rfork
667 cfa37a7b 2004-04-10 devnull flags specified by the option letters
669 cfa37a7b 2004-04-10 devnull .IR fork (2)).
671 cfa37a7b 2004-04-10 devnull .I flags
672 cfa37a7b 2004-04-10 devnull are given, they default to
673 cfa37a7b 2004-04-10 devnull .BR ens .
675 cfa37a7b 2004-04-10 devnull .I flags
676 cfa37a7b 2004-04-10 devnull and their meanings are:
679 cfa37a7b 2004-04-10 devnull .BR RFNAMEG ;
682 cfa37a7b 2004-04-10 devnull .BR RFCNAMEG ;
685 cfa37a7b 2004-04-10 devnull .BR RFENVG ;
688 cfa37a7b 2004-04-10 devnull .BR RFCENVG ;
691 cfa37a7b 2004-04-10 devnull .BR RFNOTEG ;
694 cfa37a7b 2004-04-10 devnull .BR RFFDG ;
697 cfa37a7b 2004-04-10 devnull .BR RFCFDG ;
701 cfa37a7b 2004-04-10 devnull .BR RFNOMNT .
703 cfa37a7b 2004-04-10 devnull .BI "shift [" n "]"
705 cfa37a7b 2004-04-10 devnull Delete the first
707 cfa37a7b 2004-04-10 devnull (default 1)
708 cfa37a7b 2004-04-10 devnull elements of
709 cfa37a7b 2004-04-10 devnull .BR $* .
711 cfa37a7b 2004-04-10 devnull .BI "wait [" pid "]"
713 cfa37a7b 2004-04-10 devnull Wait for the process with the given
715 cfa37a7b 2004-04-10 devnull to exit.
718 cfa37a7b 2004-04-10 devnull is given, all outstanding processes are waited for.
720 cfa37a7b 2004-04-10 devnull .BI whatis " name ..."
722 cfa37a7b 2004-04-10 devnull Print the value of each
724 cfa37a7b 2004-04-10 devnull in a form suitable for input to
725 cfa37a7b 2004-04-10 devnull .IR rc .
726 cfa37a7b 2004-04-10 devnull The output is
727 cfa37a7b 2004-04-10 devnull an assignment to any variable,
728 cfa37a7b 2004-04-10 devnull the definition of any function,
729 cfa37a7b 2004-04-10 devnull a call to
730 cfa37a7b 2004-04-10 devnull .B builtin
731 cfa37a7b 2004-04-10 devnull for any built-in command, or
732 cfa37a7b 2004-04-10 devnull the completed pathname of any executable file.
734 cfa37a7b 2004-04-10 devnull .BI ~ " subject pattern ..."
737 cfa37a7b 2004-04-10 devnull .I subject
738 cfa37a7b 2004-04-10 devnull is matched against each
739 cfa37a7b 2004-04-10 devnull .I pattern
740 cfa37a7b 2004-04-10 devnull in sequence.
741 cfa37a7b 2004-04-10 devnull If it matches any pattern,
742 cfa37a7b 2004-04-10 devnull .B $status
743 cfa37a7b 2004-04-10 devnull is set to zero.
744 cfa37a7b 2004-04-10 devnull Otherwise,
745 cfa37a7b 2004-04-10 devnull .B $status
746 cfa37a7b 2004-04-10 devnull is set to one.
747 cfa37a7b 2004-04-10 devnull Patterns are the same as for file name matching, except that
749 cfa37a7b 2004-04-10 devnull and the first character of
753 cfa37a7b 2004-04-10 devnull need not be matched explicitly.
755 cfa37a7b 2004-04-10 devnull .I patterns
756 cfa37a7b 2004-04-10 devnull are not subjected to
757 cfa37a7b 2004-04-10 devnull file name matching before the
759 cfa37a7b 2004-04-10 devnull command is executed, so they need not be enclosed in quotation marks.
761 cfa37a7b 2004-04-10 devnull .SS Environment
763 cfa37a7b 2004-04-10 devnull .I environment
764 cfa37a7b 2004-04-10 devnull is a list of strings made available to executing binaries by the
767 cfa37a7b 2004-04-10 devnull creates an environment entry for each variable whose value is non-empty,
768 cfa37a7b 2004-04-10 devnull and for each function.
769 cfa37a7b 2004-04-10 devnull The string for a variable entry has the variable's name followed by
771 cfa37a7b 2004-04-10 devnull and its value.
772 cfa37a7b 2004-04-10 devnull If the value has more than one component, these
773 c8b6342d 2005-01-13 devnull are separated by SOH (001)
774 cfa37a7b 2004-04-10 devnull characters.
775 cfa37a7b 2004-04-10 devnull The string for a function is just the
777 cfa37a7b 2004-04-10 devnull input that defines the function.
778 cfa37a7b 2004-04-10 devnull The name of a function in the environment is the function name
779 cfa37a7b 2004-04-10 devnull preceded by
780 cfa37a7b 2004-04-10 devnull .LR fn# .
784 cfa37a7b 2004-04-10 devnull starts executing it reads variable and function definitions from its
785 cfa37a7b 2004-04-10 devnull environment.
786 cfa37a7b 2004-04-10 devnull .SS Special Variables
787 cfa37a7b 2004-04-10 devnull The following variables are set or used by
788 cfa37a7b 2004-04-10 devnull .IR rc .
790 cfa37a7b 2004-04-10 devnull .TP \w'\fL$promptXX'u
793 cfa37a7b 2004-04-10 devnull .IR rc 's
794 cfa37a7b 2004-04-10 devnull argument list during initialization.
795 cfa37a7b 2004-04-10 devnull Whenever a
797 cfa37a7b 2004-04-10 devnull command or a function is executed, the current value is saved and
799 cfa37a7b 2004-04-10 devnull receives the new argument list.
800 cfa37a7b 2004-04-10 devnull The saved value is restored on completion of the
802 cfa37a7b 2004-04-10 devnull or function.
804 cfa37a7b 2004-04-10 devnull .B $apid
805 cfa37a7b 2004-04-10 devnull Whenever a process is started asynchronously with
807 cfa37a7b 2004-04-10 devnull .B $apid
808 cfa37a7b 2004-04-10 devnull is set to its process id.
810 cfa37a7b 2004-04-10 devnull .B $home
811 cfa37a7b 2004-04-10 devnull The default directory for
812 cfa37a7b 2004-04-10 devnull .BR cd .
815 cfa37a7b 2004-04-10 devnull The input field separators used in backquote substitutions.
818 cfa37a7b 2004-04-10 devnull is not set in
819 cfa37a7b 2004-04-10 devnull .IR rc 's
820 cfa37a7b 2004-04-10 devnull environment, it is initialized to blank, tab and newline.
822 cfa37a7b 2004-04-10 devnull .B $path
823 cfa37a7b 2004-04-10 devnull The search path used to find commands and input files
826 cfa37a7b 2004-04-10 devnull command.
827 cfa37a7b 2004-04-10 devnull If not set in the environment, it is initialized by
828 058b0118 2005-01-03 devnull parsing the
829 058b0118 2005-01-03 devnull .B $PATH
830 058b0118 2005-01-03 devnull variable
832 058b0118 2005-01-03 devnull .IR sh (1))
834 cfa37a7b 2004-04-10 devnull .BR "path=(.\ /bin)" .
835 058b0118 2005-01-03 devnull The variables
836 058b0118 2005-01-03 devnull .B $path
838 058b0118 2005-01-03 devnull .B $PATH
839 058b0118 2005-01-03 devnull are maintained together: changes to one will be reflected in the other.
840 058b0118 2005-01-03 devnull .\" Its use is discouraged; instead use
841 058b0118 2005-01-03 devnull .\" .IR bind (1)
842 058b0118 2005-01-03 devnull .\" to build a
843 058b0118 2005-01-03 devnull .\" .B /bin
844 058b0118 2005-01-03 devnull .\" containing what's needed.
847 cfa37a7b 2004-04-10 devnull Set during initialization to
848 cfa37a7b 2004-04-10 devnull .IR rc 's
849 cfa37a7b 2004-04-10 devnull process id.
851 cfa37a7b 2004-04-10 devnull .B $prompt
854 cfa37a7b 2004-04-10 devnull is run interactively, the first component of
855 cfa37a7b 2004-04-10 devnull .B $prompt
856 cfa37a7b 2004-04-10 devnull is printed before reading each command.
857 cfa37a7b 2004-04-10 devnull The second component is printed whenever a newline is typed and more lines
858 cfa37a7b 2004-04-10 devnull are required to complete the command.
859 cfa37a7b 2004-04-10 devnull If not set in the environment, it is initialized by
860 cfa37a7b 2004-04-10 devnull .BR "prompt=('%\ '\ '\ ')" .
862 cfa37a7b 2004-04-10 devnull .B $status
863 cfa37a7b 2004-04-10 devnull Set to the wait message of the last-executed program.
864 cfa37a7b 2004-04-10 devnull (unless started with
869 cfa37a7b 2004-04-10 devnull also change
870 cfa37a7b 2004-04-10 devnull .BR $status .
871 cfa37a7b 2004-04-10 devnull Its value is used to control execution in
872 cfa37a7b 2004-04-10 devnull .BR && ,
873 cfa37a7b 2004-04-10 devnull .BR || ,
876 cfa37a7b 2004-04-10 devnull .B while
877 cfa37a7b 2004-04-10 devnull commands.
880 cfa37a7b 2004-04-10 devnull exits at end-of-file of its input or on executing an
882 cfa37a7b 2004-04-10 devnull command with no argument,
883 cfa37a7b 2004-04-10 devnull .B $status
884 cfa37a7b 2004-04-10 devnull is its exit status.
886 cfa37a7b 2004-04-10 devnull .SS Invocation
889 cfa37a7b 2004-04-10 devnull is started with no arguments it reads commands from standard input.
890 cfa37a7b 2004-04-10 devnull Otherwise its first non-flag argument is the name of a file from which
891 cfa37a7b 2004-04-10 devnull to read commands (but see
894 cfa37a7b 2004-04-10 devnull Subsequent arguments become the initial value of
895 cfa37a7b 2004-04-10 devnull .BR $* .
897 cfa37a7b 2004-04-10 devnull accepts the following command-line flags.
899 cfa37a7b 2004-04-10 devnull .TP \w'\fL-c\ \fIstring\fLXX'u
900 cfa37a7b 2004-04-10 devnull .BI -c " string"
901 cfa37a7b 2004-04-10 devnull Commands are read from
902 cfa37a7b 2004-04-10 devnull .IR string .
905 cfa37a7b 2004-04-10 devnull Print out exit status after any command where the status is non-null.
909 cfa37a7b 2004-04-10 devnull .B $status
910 cfa37a7b 2004-04-10 devnull is non-null after executing a simple command.
915 cfa37a7b 2004-04-10 devnull is present, or
917 cfa37a7b 2004-04-10 devnull is given no arguments and its standard input is a terminal,
918 cfa37a7b 2004-04-10 devnull it runs interactively.
919 cfa37a7b 2004-04-10 devnull Commands are prompted for using
920 cfa37a7b 2004-04-10 devnull .BR $prompt .
923 cfa37a7b 2004-04-10 devnull Makes sure
925 cfa37a7b 2004-04-10 devnull is not run interactively.
930 cfa37a7b 2004-04-10 devnull is given or the first character of argument zero is
933 cfa37a7b 2004-04-10 devnull reads commands from
934 cfa37a7b 2004-04-10 devnull .BR $home/lib/profile ,
935 cfa37a7b 2004-04-10 devnull if it exists, before reading its normal input.
938 cfa37a7b 2004-04-10 devnull A no-op.
941 cfa37a7b 2004-04-10 devnull A no-op.
944 cfa37a7b 2004-04-10 devnull Echo input on file descriptor 2 as it is read.
947 cfa37a7b 2004-04-10 devnull Print each simple command before executing it.
950 cfa37a7b 2004-04-10 devnull Print debugging information (internal form of commands
951 cfa37a7b 2004-04-10 devnull as they are executed).
953 cfa37a7b 2004-04-10 devnull .SH SOURCE
954 c3674de4 2005-01-11 devnull .B \*9/src/cmd/rc
955 cfa37a7b 2004-04-10 devnull .SH "SEE ALSO"
956 cfa37a7b 2004-04-10 devnull Tom Duff,
957 cfa37a7b 2004-04-10 devnull ``Rc \- The Plan 9 Shell''.
958 cfa37a7b 2004-04-10 devnull .SH BUGS
959 cfa37a7b 2004-04-10 devnull There should be a way to match patterns against whole lists rather than
960 cfa37a7b 2004-04-10 devnull just single strings.
964 cfa37a7b 2004-04-10 devnull to check the value of
965 cfa37a7b 2004-04-10 devnull .B $status
967 cfa37a7b 2004-04-10 devnull .BR $status .
969 11c751cf 2005-01-07 devnull Functions that use here documents don't work.
971 cfa37a7b 2004-04-10 devnull Free carets don't get inserted next to keywords.
974 11c751cf 2005-01-07 devnull .BI <{ command }
975 11c751cf 2005-01-07 devnull syntax depends on the underlying operating system
976 11c751cf 2005-01-07 devnull providing a file descriptor device tree at
977 11c751cf 2005-01-07 devnull .BR /dev/fd .
979 11c751cf 2005-01-07 devnull By default, FreeBSD 5
980 11c751cf 2005-01-07 devnull does not provide file descriptors greater than 2
982 11c751cf 2005-01-07 devnull .BR /dev/fd .
983 11c751cf 2005-01-07 devnull To fix this, add
986 11c751cf 2005-01-07 devnull /fdescfs /dev/fd fdescfs rw 0 0
990 11c751cf 2005-01-07 devnull .BR /etc/fstab ,
991 11c751cf 2005-01-07 devnull and then
992 11c751cf 2005-01-07 devnull .B mount
993 11c751cf 2005-01-07 devnull .BR /dev/fd .
994 11c751cf 2005-01-07 devnull (Adding the line to
995 11c751cf 2005-01-07 devnull .B fstab
996 11c751cf 2005-01-07 devnull ensures causes FreeBSD to mount the file system
997 11c751cf 2005-01-07 devnull automatically at boot time.)
