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 d32deab1 2020-08-16 rsc .MR 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 d32deab1 2020-08-16 rsc .MR 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 ff74f7cd 2020-05-05 rsc # ; & | ^ $ ` ' { } ( ) < >
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
294 cfa37a7b 2004-04-10 devnull will insert the
296 cfa37a7b 2004-04-10 devnull operator automatically between words that are not separated by white space.
299 cfa37a7b 2004-04-10 devnull .B cc -$flags $stem.c
301 cfa37a7b 2004-04-10 devnull is equivalent to
303 cfa37a7b 2004-04-10 devnull .B cc -^$flags $stem^.c
304 cfa37a7b 2004-04-10 devnull .SS I/O Redirections
305 cfa37a7b 2004-04-10 devnull The sequence
306 cfa37a7b 2004-04-10 devnull .BI > file
307 cfa37a7b 2004-04-10 devnull redirects the standard output file (file descriptor 1, normally the
308 cfa37a7b 2004-04-10 devnull terminal) to the named
309 cfa37a7b 2004-04-10 devnull .IR file ;
310 cfa37a7b 2004-04-10 devnull .BI >> file
311 cfa37a7b 2004-04-10 devnull appends standard output to the file.
312 cfa37a7b 2004-04-10 devnull The standard input file (file descriptor 0, also normally the terminal)
313 cfa37a7b 2004-04-10 devnull may be redirected from a file by the sequence
314 cfa37a7b 2004-04-10 devnull .BI < file \f1,
315 cfa37a7b 2004-04-10 devnull or from an inline `here document'
316 cfa37a7b 2004-04-10 devnull by the sequence
317 cfa37a7b 2004-04-10 devnull .BI << eof-marker\f1.
318 cfa37a7b 2004-04-10 devnull The contents of a here document are lines of text taken from the command
319 cfa37a7b 2004-04-10 devnull input stream up to a line containing nothing but the
320 cfa37a7b 2004-04-10 devnull .IR eof-marker ,
321 cfa37a7b 2004-04-10 devnull which may be either a quoted or unquoted word.
323 cfa37a7b 2004-04-10 devnull .I eof-marker
324 cfa37a7b 2004-04-10 devnull is unquoted, variable names of the form
325 cfa37a7b 2004-04-10 devnull .BI $ word
326 cfa37a7b 2004-04-10 devnull have their values substituted from
328 cfa37a7b 2004-04-10 devnull environment.
330 cfa37a7b 2004-04-10 devnull .BI $ word
331 cfa37a7b 2004-04-10 devnull is followed by a caret
332 cfa37a7b 2004-04-10 devnull .RB ( ^ ),
333 cfa37a7b 2004-04-10 devnull the caret is deleted.
335 cfa37a7b 2004-04-10 devnull .I eof-marker
336 cfa37a7b 2004-04-10 devnull is quoted, no substitution occurs.
338 cfa37a7b 2004-04-10 devnull Redirections may be applied to a file-descriptor other than standard input
339 cfa37a7b 2004-04-10 devnull or output by qualifying the redirection operator
340 cfa37a7b 2004-04-10 devnull with a number in square brackets.
341 cfa37a7b 2004-04-10 devnull For example, the diagnostic output (file descriptor 2)
342 cfa37a7b 2004-04-10 devnull may be redirected by writing
343 cfa37a7b 2004-04-10 devnull .BR "cc junk.c >[2]junk" .
345 cfa37a7b 2004-04-10 devnull A file descriptor may be redirected to an already open descriptor by writing
346 cfa37a7b 2004-04-10 devnull .BI >[ fd0 = fd1 ]
348 cfa37a7b 2004-04-10 devnull .BI <[ fd0 = fd1 ]\f1.
350 cfa37a7b 2004-04-10 devnull is a previously opened file descriptor and
352 7d6a248f 2020-05-05 rsc becomes a new copy (in the sense of
353 d32deab1 2020-08-16 rsc .MR dup (3) )
355 cfa37a7b 2004-04-10 devnull A file descriptor may be closed by writing
356 cfa37a7b 2004-04-10 devnull .BI >[ fd0 =]
358 cfa37a7b 2004-04-10 devnull .BI <[ fd0 =]\f1.
360 cfa37a7b 2004-04-10 devnull Redirections are executed from left to right.
361 cfa37a7b 2004-04-10 devnull Therefore,
362 cfa37a7b 2004-04-10 devnull .B cc junk.c >/dev/null >[2=1]
364 cfa37a7b 2004-04-10 devnull .B cc junk.c >[2=1] >/dev/null
365 cfa37a7b 2004-04-10 devnull have different effects: the first puts standard output in
366 cfa37a7b 2004-04-10 devnull .BR /dev/null
367 cfa37a7b 2004-04-10 devnull and then puts diagnostic output in the same place, where the second
368 cfa37a7b 2004-04-10 devnull directs diagnostic output to the terminal and sends standard output to
369 cfa37a7b 2004-04-10 devnull .BR /dev/null .
370 cfa37a7b 2004-04-10 devnull .SS Compound Commands
371 cfa37a7b 2004-04-10 devnull A pair of commands separated by a pipe operator
372 cfa37a7b 2004-04-10 devnull .RB ( | )
373 cfa37a7b 2004-04-10 devnull is a command.
374 cfa37a7b 2004-04-10 devnull The standard output of the left command is sent through a pipe
375 cfa37a7b 2004-04-10 devnull to the standard input of the right command.
376 cfa37a7b 2004-04-10 devnull The pipe operator may be decorated
377 cfa37a7b 2004-04-10 devnull to use different file descriptors.
378 cfa37a7b 2004-04-10 devnull .BI |[ fd ]
379 cfa37a7b 2004-04-10 devnull connects the output end of the pipe to file descriptor
381 cfa37a7b 2004-04-10 devnull rather than 1.
382 cfa37a7b 2004-04-10 devnull .BI |[ fd0 = fd1 ]
383 cfa37a7b 2004-04-10 devnull connects output to
385 cfa37a7b 2004-04-10 devnull of the left command and input to
387 cfa37a7b 2004-04-10 devnull of the right command.
389 cfa37a7b 2004-04-10 devnull A pair of commands separated by
393 cfa37a7b 2004-04-10 devnull is a command.
394 cfa37a7b 2004-04-10 devnull In either case, the left command is executed and its exit status examined.
395 cfa37a7b 2004-04-10 devnull If the operator is
397 cfa37a7b 2004-04-10 devnull the right command is executed if the left command's status is null.
399 cfa37a7b 2004-04-10 devnull causes the right command to be executed if the left command's status is non-null.
401 cfa37a7b 2004-04-10 devnull The exit status of a command may be inverted (non-null is changed to null, null
402 cfa37a7b 2004-04-10 devnull is changed to non-null) by preceding it with a
407 cfa37a7b 2004-04-10 devnull operator has highest precedence, and is left-associative (i.e. binds tighter
408 cfa37a7b 2004-04-10 devnull to the left than the right).
410 cfa37a7b 2004-04-10 devnull has intermediate precedence, and
414 cfa37a7b 2004-04-10 devnull have the lowest precedence.
416 cfa37a7b 2004-04-10 devnull The unary
418 cfa37a7b 2004-04-10 devnull operator, with precedence equal to
420 cfa37a7b 2004-04-10 devnull causes its operand to be executed in a subshell.
422 cfa37a7b 2004-04-10 devnull Each of the following is a command.
428 cfa37a7b 2004-04-10 devnull .I command
432 cfa37a7b 2004-04-10 devnull is a sequence of commands, separated by
435 cfa37a7b 2004-04-10 devnull or newline.
436 cfa37a7b 2004-04-10 devnull It is executed and
437 cfa37a7b 2004-04-10 devnull if its exit status is null, the
438 cfa37a7b 2004-04-10 devnull .I command
439 cfa37a7b 2004-04-10 devnull is executed.
441 cfa37a7b 2004-04-10 devnull .B if not
442 cfa37a7b 2004-04-10 devnull .I command
444 cfa37a7b 2004-04-10 devnull The immediately preceding command must have been
445 cfa37a7b 2004-04-10 devnull .BI if( list )
446 cfa37a7b 2004-04-10 devnull .IR command .
447 cfa37a7b 2004-04-10 devnull If its condition was non-zero, the
448 cfa37a7b 2004-04-10 devnull .I command
449 cfa37a7b 2004-04-10 devnull is executed.
451 cfa37a7b 2004-04-10 devnull .BI for( name
453 cfa37a7b 2004-04-10 devnull .IB arguments )
454 cfa37a7b 2004-04-10 devnull .I command
456 cfa37a7b 2004-04-10 devnull .BI for( name )
457 cfa37a7b 2004-04-10 devnull .I command
460 cfa37a7b 2004-04-10 devnull .I command
461 cfa37a7b 2004-04-10 devnull is executed once for each
462 7d6a248f 2020-05-05 rsc .IR argument
463 cfa37a7b 2004-04-10 devnull with that argument assigned to
464 cfa37a7b 2004-04-10 devnull .IR name .
465 cfa37a7b 2004-04-10 devnull If the argument list is omitted,
467 cfa37a7b 2004-04-10 devnull is used.
469 cfa37a7b 2004-04-10 devnull .BI while( list )
470 cfa37a7b 2004-04-10 devnull .I command
474 cfa37a7b 2004-04-10 devnull is executed repeatedly until its exit status is non-null.
475 cfa37a7b 2004-04-10 devnull Each time it returns null status, the
476 cfa37a7b 2004-04-10 devnull .I command
477 cfa37a7b 2004-04-10 devnull is executed.
478 cfa37a7b 2004-04-10 devnull An empty
480 cfa37a7b 2004-04-10 devnull is taken to give null status.
482 cfa37a7b 2004-04-10 devnull .BI "switch(" argument "){" list }
485 cfa37a7b 2004-04-10 devnull .IR list
486 cfa37a7b 2004-04-10 devnull is searched for simple commands beginning with the word
487 cfa37a7b 2004-04-10 devnull .BR case .
488 cfa37a7b 2004-04-10 devnull (The search is only at the `top level' of the
489 cfa37a7b 2004-04-10 devnull .IR list .
490 cfa37a7b 2004-04-10 devnull That is,
491 cfa37a7b 2004-04-10 devnull .B cases
492 cfa37a7b 2004-04-10 devnull in nested constructs are not found.)
493 cfa37a7b 2004-04-10 devnull .I Argument
494 cfa37a7b 2004-04-10 devnull is matched against each word following
496 cfa37a7b 2004-04-10 devnull using the pattern-matching algorithm described above, except that
498 cfa37a7b 2004-04-10 devnull and the first characters of
502 cfa37a7b 2004-04-10 devnull need not be matched explicitly.
503 cfa37a7b 2004-04-10 devnull When a match is found, commands in the list are executed up to the next
504 cfa37a7b 2004-04-10 devnull following
506 cfa37a7b 2004-04-10 devnull command (at the top level) or the closing brace.
508 cfa37a7b 2004-04-10 devnull .BI { list }
510 cfa37a7b 2004-04-10 devnull Braces serve to alter the grouping of commands implied by operator
511 cfa37a7b 2004-04-10 devnull priorities.
514 cfa37a7b 2004-04-10 devnull is a sequence of commands separated by
517 cfa37a7b 2004-04-10 devnull or newline.
519 cfa37a7b 2004-04-10 devnull .BI "fn " name { list }
521 cfa37a7b 2004-04-10 devnull .BI "fn " name
523 cfa37a7b 2004-04-10 devnull The first form defines a function with the given
524 cfa37a7b 2004-04-10 devnull .IR name .
525 cfa37a7b 2004-04-10 devnull Subsequently, whenever a command whose first argument is
527 cfa37a7b 2004-04-10 devnull is encountered, the current value of
528 cfa37a7b 2004-04-10 devnull the remainder of the command's argument list will be assigned to
529 cfa37a7b 2004-04-10 devnull .BR $* ,
530 cfa37a7b 2004-04-10 devnull after saving its current value, and
532 cfa37a7b 2004-04-10 devnull will execute the
533 cfa37a7b 2004-04-10 devnull .IR list .
534 cfa37a7b 2004-04-10 devnull The second form removes
535 cfa37a7b 2004-04-10 devnull .IR name 's
536 cfa37a7b 2004-04-10 devnull function definition.
538 cfa37a7b 2004-04-10 devnull .BI "fn " note { list }
541 cfa37a7b 2004-04-10 devnull .BI "fn " note
543 cfa37a7b 2004-04-10 devnull A function with a special name will be called when
545 cfa37a7b 2004-04-10 devnull receives a corresponding note; see
546 d32deab1 2020-08-16 rsc .MR notify (3) .
547 cfa37a7b 2004-04-10 devnull The valid note names (and corresponding notes) are
548 cfa37a7b 2004-04-10 devnull .B sighup
549 cfa37a7b 2004-04-10 devnull .RB ( hangup ),
550 cfa37a7b 2004-04-10 devnull .B sigint
551 cfa37a7b 2004-04-10 devnull .RB ( interrupt ),
552 cfa37a7b 2004-04-10 devnull .BR sigalrm
553 cfa37a7b 2004-04-10 devnull .RB ( alarm ),
555 cfa37a7b 2004-04-10 devnull .B sigfpe
556 cfa37a7b 2004-04-10 devnull (floating point trap).
557 cfa37a7b 2004-04-10 devnull By default
559 cfa37a7b 2004-04-10 devnull exits on receiving any signal, except when run interactively,
560 cfa37a7b 2004-04-10 devnull in which case interrupts and quits normally cause
562 cfa37a7b 2004-04-10 devnull to stop whatever it's doing and start reading a new command.
563 cfa37a7b 2004-04-10 devnull The second form causes
565 cfa37a7b 2004-04-10 devnull to handle a signal in the default manner.
567 cfa37a7b 2004-04-10 devnull recognizes an artificial note,
568 cfa37a7b 2004-04-10 devnull .BR sigexit ,
569 cfa37a7b 2004-04-10 devnull which occurs when
571 cfa37a7b 2004-04-10 devnull is about to finish executing.
573 cfa37a7b 2004-04-10 devnull .IB name = "argument command"
575 cfa37a7b 2004-04-10 devnull Any command may be preceded by a sequence of assignments
576 cfa37a7b 2004-04-10 devnull interspersed with redirections.
577 cfa37a7b 2004-04-10 devnull The assignments remain in effect until the end of the command, unless
578 cfa37a7b 2004-04-10 devnull the command is empty (i.e. the assignments stand alone), in which case
579 cfa37a7b 2004-04-10 devnull they are effective until rescinded by later assignments.
581 cfa37a7b 2004-04-10 devnull .SS Built-in Commands
582 cfa37a7b 2004-04-10 devnull These commands are executed internally by
583 cfa37a7b 2004-04-10 devnull .IR rc ,
584 cfa37a7b 2004-04-10 devnull usually because their execution changes or depends on
585 cfa37a7b 2004-04-10 devnull .IR rc 's
586 cfa37a7b 2004-04-10 devnull internal state.
589 cfa37a7b 2004-04-10 devnull .BI . " file ..."
591 cfa37a7b 2004-04-10 devnull Execute commands from
592 cfa37a7b 2004-04-10 devnull .IR file .
594 cfa37a7b 2004-04-10 devnull is set for the duration to the remainder of the argument list following
595 cfa37a7b 2004-04-10 devnull .IR file .
597 cfa37a7b 2004-04-10 devnull is searched for using
598 cfa37a7b 2004-04-10 devnull .BR $path .
600 cfa37a7b 2004-04-10 devnull .BI builtin " command ..."
603 cfa37a7b 2004-04-10 devnull .I command
604 cfa37a7b 2004-04-10 devnull as usual except that any function named
605 cfa37a7b 2004-04-10 devnull .I command
606 cfa37a7b 2004-04-10 devnull is ignored in favor of the built-in meaning.
608 cfa37a7b 2004-04-10 devnull .BI "cd [" dir "]"
610 cfa37a7b 2004-04-10 devnull Change the current directory to
611 cfa37a7b 2004-04-10 devnull .IR dir .
612 cfa37a7b 2004-04-10 devnull The default argument is
613 cfa37a7b 2004-04-10 devnull .BR $home .
615 cfa37a7b 2004-04-10 devnull is searched for in each of the directories mentioned in
616 cfa37a7b 2004-04-10 devnull .BR $cdpath .
618 cfa37a7b 2004-04-10 devnull .BI "eval [" "arg ..." "]"
620 cfa37a7b 2004-04-10 devnull The arguments are concatenated separated by spaces into a single string,
621 cfa37a7b 2004-04-10 devnull read as input to
622 cfa37a7b 2004-04-10 devnull .IR rc ,
623 cfa37a7b 2004-04-10 devnull and executed.
625 cfa37a7b 2004-04-10 devnull .BI "exec [" "command ..." "]"
627 cfa37a7b 2004-04-10 devnull This instance of
629 cfa37a7b 2004-04-10 devnull replaces itself with the given (non-built-in)
630 cfa37a7b 2004-04-10 devnull .IR command .
632 cfa37a7b 2004-04-10 devnull .BI "flag " f " [+-]"
634 cfa37a7b 2004-04-10 devnull Either set
635 cfa37a7b 2004-04-10 devnull .RB ( + ),
637 cfa37a7b 2004-04-10 devnull .RB ( - ),
638 cfa37a7b 2004-04-10 devnull or test (neither
642 cfa37a7b 2004-04-10 devnull the flag
646 cfa37a7b 2004-04-10 devnull is a single character, one of the command line flags (see Invocation, below).
648 cfa37a7b 2004-04-10 devnull .BI "exit [" status "]"
650 cfa37a7b 2004-04-10 devnull Exit with the given exit status.
651 cfa37a7b 2004-04-10 devnull If none is given, the current value of
652 cfa37a7b 2004-04-10 devnull .B $status
653 cfa37a7b 2004-04-10 devnull is used.
655 cfa37a7b 2004-04-10 devnull .BR "rfork " [ nNeEsfFm ]
657 cfa37a7b 2004-04-10 devnull Become a new process group using
658 cfa37a7b 2004-04-10 devnull .BI rfork( flags )
660 cfa37a7b 2004-04-10 devnull .I flags
661 cfa37a7b 2004-04-10 devnull is composed of the bitwise OR of the
662 cfa37a7b 2004-04-10 devnull .B rfork
663 cfa37a7b 2004-04-10 devnull flags specified by the option letters
665 d32deab1 2020-08-16 rsc .MR fork (2) ).
667 cfa37a7b 2004-04-10 devnull .I flags
668 cfa37a7b 2004-04-10 devnull are given, they default to
669 cfa37a7b 2004-04-10 devnull .BR ens .
671 cfa37a7b 2004-04-10 devnull .I flags
672 cfa37a7b 2004-04-10 devnull and their meanings are:
675 cfa37a7b 2004-04-10 devnull .BR RFNAMEG ;
678 cfa37a7b 2004-04-10 devnull .BR RFCNAMEG ;
681 cfa37a7b 2004-04-10 devnull .BR RFENVG ;
684 cfa37a7b 2004-04-10 devnull .BR RFCENVG ;
687 cfa37a7b 2004-04-10 devnull .BR RFNOTEG ;
690 cfa37a7b 2004-04-10 devnull .BR RFFDG ;
693 cfa37a7b 2004-04-10 devnull .BR RFCFDG ;
697 cfa37a7b 2004-04-10 devnull .BR RFNOMNT .
699 cfa37a7b 2004-04-10 devnull .BI "shift [" n "]"
701 cfa37a7b 2004-04-10 devnull Delete the first
703 cfa37a7b 2004-04-10 devnull (default 1)
704 cfa37a7b 2004-04-10 devnull elements of
705 cfa37a7b 2004-04-10 devnull .BR $* .
707 cfa37a7b 2004-04-10 devnull .BI "wait [" pid "]"
709 cfa37a7b 2004-04-10 devnull Wait for the process with the given
711 cfa37a7b 2004-04-10 devnull to exit.
714 cfa37a7b 2004-04-10 devnull is given, all outstanding processes are waited for.
716 cfa37a7b 2004-04-10 devnull .BI whatis " name ..."
718 cfa37a7b 2004-04-10 devnull Print the value of each
720 cfa37a7b 2004-04-10 devnull in a form suitable for input to
721 cfa37a7b 2004-04-10 devnull .IR rc .
722 cfa37a7b 2004-04-10 devnull The output is
723 cfa37a7b 2004-04-10 devnull an assignment to any variable,
724 cfa37a7b 2004-04-10 devnull the definition of any function,
725 cfa37a7b 2004-04-10 devnull a call to
726 cfa37a7b 2004-04-10 devnull .B builtin
727 cfa37a7b 2004-04-10 devnull for any built-in command, or
728 cfa37a7b 2004-04-10 devnull the completed pathname of any executable file.
730 cfa37a7b 2004-04-10 devnull .BI ~ " subject pattern ..."
733 cfa37a7b 2004-04-10 devnull .I subject
734 cfa37a7b 2004-04-10 devnull is matched against each
735 cfa37a7b 2004-04-10 devnull .I pattern
736 cfa37a7b 2004-04-10 devnull in sequence.
737 cfa37a7b 2004-04-10 devnull If it matches any pattern,
738 cfa37a7b 2004-04-10 devnull .B $status
739 cfa37a7b 2004-04-10 devnull is set to zero.
740 cfa37a7b 2004-04-10 devnull Otherwise,
741 cfa37a7b 2004-04-10 devnull .B $status
742 cfa37a7b 2004-04-10 devnull is set to one.
743 cfa37a7b 2004-04-10 devnull Patterns are the same as for file name matching, except that
745 cfa37a7b 2004-04-10 devnull and the first character of
749 cfa37a7b 2004-04-10 devnull need not be matched explicitly.
751 cfa37a7b 2004-04-10 devnull .I patterns
752 cfa37a7b 2004-04-10 devnull are not subjected to
753 cfa37a7b 2004-04-10 devnull file name matching before the
755 cfa37a7b 2004-04-10 devnull command is executed, so they need not be enclosed in quotation marks.
757 cfa37a7b 2004-04-10 devnull .SS Environment
759 cfa37a7b 2004-04-10 devnull .I environment
760 cfa37a7b 2004-04-10 devnull is a list of strings made available to executing binaries by the
763 cfa37a7b 2004-04-10 devnull creates an environment entry for each variable whose value is non-empty,
764 cfa37a7b 2004-04-10 devnull and for each function.
765 cfa37a7b 2004-04-10 devnull The string for a variable entry has the variable's name followed by
767 cfa37a7b 2004-04-10 devnull and its value.
768 cfa37a7b 2004-04-10 devnull If the value has more than one component, these
769 c8b6342d 2005-01-13 devnull are separated by SOH (001)
770 cfa37a7b 2004-04-10 devnull characters.
771 cfa37a7b 2004-04-10 devnull The string for a function is just the
773 cfa37a7b 2004-04-10 devnull input that defines the function.
774 cfa37a7b 2004-04-10 devnull The name of a function in the environment is the function name
775 cfa37a7b 2004-04-10 devnull preceded by
776 cfa37a7b 2004-04-10 devnull .LR fn# .
780 cfa37a7b 2004-04-10 devnull starts executing it reads variable and function definitions from its
781 cfa37a7b 2004-04-10 devnull environment.
782 cfa37a7b 2004-04-10 devnull .SS Special Variables
783 cfa37a7b 2004-04-10 devnull The following variables are set or used by
784 cfa37a7b 2004-04-10 devnull .IR rc .
786 cfa37a7b 2004-04-10 devnull .TP \w'\fL$promptXX'u
789 cfa37a7b 2004-04-10 devnull .IR rc 's
790 cfa37a7b 2004-04-10 devnull argument list during initialization.
791 cfa37a7b 2004-04-10 devnull Whenever a
793 cfa37a7b 2004-04-10 devnull command or a function is executed, the current value is saved and
795 cfa37a7b 2004-04-10 devnull receives the new argument list.
796 cfa37a7b 2004-04-10 devnull The saved value is restored on completion of the
798 cfa37a7b 2004-04-10 devnull or function.
800 cfa37a7b 2004-04-10 devnull .B $apid
801 cfa37a7b 2004-04-10 devnull Whenever a process is started asynchronously with
803 cfa37a7b 2004-04-10 devnull .B $apid
804 cfa37a7b 2004-04-10 devnull is set to its process id.
806 cfa37a7b 2004-04-10 devnull .B $home
807 cfa37a7b 2004-04-10 devnull The default directory for
808 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 d32deab1 2020-08-16 rsc .MR 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.
972 11c751cf 2005-01-07 devnull .BI <{ command }
973 11c751cf 2005-01-07 devnull syntax depends on the underlying operating system
974 11c751cf 2005-01-07 devnull providing a file descriptor device tree at
975 11c751cf 2005-01-07 devnull .BR /dev/fd .
977 519fe613 2011-10-31 rsc Some FreeBSD installations
978 11c751cf 2005-01-07 devnull does not provide file descriptors greater than 2
980 11c751cf 2005-01-07 devnull .BR /dev/fd .
981 11c751cf 2005-01-07 devnull To fix this, add
984 11c751cf 2005-01-07 devnull /fdescfs /dev/fd fdescfs rw 0 0
988 11c751cf 2005-01-07 devnull .BR /etc/fstab ,
989 11c751cf 2005-01-07 devnull and then
990 11c751cf 2005-01-07 devnull .B mount
991 11c751cf 2005-01-07 devnull .BR /dev/fd .
992 11c751cf 2005-01-07 devnull (Adding the line to
993 11c751cf 2005-01-07 devnull .B fstab
994 11c751cf 2005-01-07 devnull ensures causes FreeBSD to mount the file system
995 11c751cf 2005-01-07 devnull automatically at boot time.)
997 b962b25e 2020-05-05 rsc Some systems require
998 b962b25e 2020-05-05 rsc .B \*9/bin/rc
999 b962b25e 2020-05-05 rsc to be listed in
1000 b962b25e 2020-05-05 rsc .B /etc/shells
1001 b962b25e 2020-05-05 rsc before it can be used as a login shell.
