Sync some manuals from bin & sbin with NetBSD-8
[minix.git] / bin / csh / csh.1
blob3c3763c1cd80a2d6172b515a2b3861b9984b8edc
1 .\"     $NetBSD: csh.1,v 1.53 2016/08/10 17:16:47 sevan Exp $
2 .\"
3 .\" Copyright (c) 1980, 1990, 1993
4 .\"     The Regents of the University of California.  All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in the
13 .\"    documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\"    may be used to endorse or promote products derived from this software
16 .\"    without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\"     @(#)csh.1       8.2 (Berkeley) 1/21/94
31 .\"
32 .Dd August 8, 2016
33 .Dt CSH 1
34 .Os
35 .Sh NAME
36 .Nm csh
37 .Nd a shell (command interpreter) with C-like syntax
38 .Sh SYNOPSIS
39 .Nm
40 .Op Fl bcefinstvVxX
41 .Op arg ...
42 .Nm
43 .Op Fl l
44 .Sh DESCRIPTION
45 The
46 .Nm
47 is a command language interpreter
48 incorporating a history mechanism (see
49 .Sx History substitutions ) ,
50 job control facilities (see
51 .Sx Jobs ) ,
52 interactive file name
53 and user name completion (see
54 .Sx File Name Completion ) ,
55 and a C-like syntax.
56 It is used both as an interactive
57 login shell and a shell script command processor.
58 .Ss Argument list processing
59 If the first argument (argument 0) to the shell is
60 .Ql Fl \& ,
61 then this is a login shell.
62 A login shell also can be specified by invoking the shell with the
63 .Ql Fl l
64 flag as the only argument.
65 .Pp
66 The rest of the flag arguments are interpreted as follows:
67 .Bl -tag -width 5n
68 .It Fl b
69 This flag forces a ``break'' from option processing, causing any further
70 shell arguments to be treated as non-option arguments.
71 The remaining arguments will not be interpreted as shell options.
72 This may be used to pass options to a shell script without confusion
73 or possible subterfuge.
74 The shell will not run a set-user ID script without this option.
75 .It Fl c
76 Commands are read from the (single) following argument which must
77 be present.
78 Any remaining arguments are placed in
79 .Ar argv .
80 .It Fl e
81 The shell exits if any invoked command terminates abnormally
82 or yields a non-zero exit status.
83 .It Fl f
84 The shell will start faster, because it will neither search for nor
85 execute commands from the file
86 .Pa \&.cshrc
87 in the invoker's home directory.
88 .It Fl i
89 The shell is interactive and prompts for its top-level input,
90 even if it appears not to be a terminal.
91 Shells are interactive without this option if their inputs
92 and outputs are terminals.
93 .It Fl l
94 The shell is a login shell (only applicable if
95 .Fl l
96 is the only flag specified).
97 .It Fl m
98 Read
99 .Pa \&.cshrc
100 even if not owned by the user.
101 This flag is normally given only by
102 .Xr su 1 .
103 .It Fl n
104 Commands are parsed, but not executed.
105 This aids in syntactic checking of shell scripts.
106 .It Fl s
107 Command input is taken from the standard input.
108 .It Fl t
109 A single line of input is read and executed.
111 .Ql \e
112 may be used to escape the newline at the end of this
113 line and continue onto another line.
114 .It Fl v
115 Causes the
116 .Ar verbose
117 variable to be set, with the effect
118 that command input is echoed after history substitution.
119 .It Fl x
120 Causes the
121 .Ar echo
122 variable to be set, so that commands are echoed immediately before execution.
123 .It Fl V
124 Causes the
125 .Ar verbose
126 variable to be set even before
127 .Pa .cshrc
128 is executed.
129 .It Fl X
130 Is to
131 .Fl x
133 .Fl V
134 is to
135 .Fl v .
138 After processing of flag arguments, if arguments remain but none of the
139 .Fl c ,
140 .Fl i ,
141 .Fl s ,
143 .Fl t
144 options were given, the first argument is taken as the name of a file of
145 commands to be executed.
146 The shell opens this file, and saves its name for possible resubstitution
147 by `$0'.
148 Since many systems use either the standard version 6 or version 7 shells
149 whose shell scripts are not compatible with this shell, the shell will
150 execute such a `standard' shell if the first character of a script
151 is not a `#', i.e., if the script does not start with a comment.
152 Remaining arguments initialize the variable
153 .Ar argv .
155 An instance of
157 begins by executing commands from the file
158 .Pa /etc/csh.cshrc
159 and,
160 if this is a login shell,
161 .Pa \&/etc/csh.login .
162 It then executes
163 commands from
164 .Pa \&.cshrc
165 in the
166 .Ar home
167 directory of the invoker, and, if this is a login shell, the file
168 .Pa \&.login
169 in the same location.
170 It is typical for users on crt's to put the command ``stty crt''
171 in their
172 .Pa \&.login
173 file, and to also invoke
174 .Xr tset 1
175 there.
177 In the normal case, the shell will begin reading commands from the
178 terminal, prompting with `% '.
179 Processing of arguments and the use of the shell to process files
180 containing command scripts will be described later.
182 The shell repeatedly performs the following actions:
183 a line of command input is read and broken into
184 .Ar words  .
185 This sequence of words is placed on the command history list and parsed.
186 Finally each command in the current line is executed.
188 When a login shell terminates it executes commands from the files
189 .Pa .logout
190 in the user's
191 .Ar home
192 directory and
193 .Pa /etc/csh.logout .
194 .Ss Lexical structure
195 The shell splits input lines into words at blanks and tabs with the
196 following exceptions.
197 The characters
198 `\*[Am]' `\&|' `;' `\*[Lt]' `\*[Gt]' `(' `)'
199 form separate words.
200 If doubled in `\*[Am]\*[Am]',
201 `\&|\&|', `\*[Lt]\*[Lt]' or `\*[Gt]\*[Gt]' these pairs form single words.
202 These parser metacharacters may be made part of other words, or prevented their
203 special meaning, by preceding them with `\e'.
204 A newline preceded by a `\e' is equivalent to a blank.
206 Strings enclosed in matched pairs of quotations,
207 `'\|', `\*(ga' or `"',
208 form parts of a word; metacharacters in these strings, including blanks
209 and tabs, do not form separate words.
210 These quotations have semantics to be described later.
211 Within pairs of `\'' or `"' characters, a newline preceded by a `\e' gives
212 a true newline character.
214 When the shell's input is not a terminal,
215 the character `#' introduces a comment that continues to the end of the
216 input line.
217 It is prevented this special meaning when preceded by `\e'
218 and in quotations using `\`', `\'', and `"'.
219 .Ss Commands
220 A simple command is a sequence of words, the first of which
221 specifies the command to be executed.
222 A simple command or
223 a sequence of simple commands separated by `\&|' characters
224 forms a pipeline.
225 The output of each command in a pipeline is connected to the input of the next.
226 Sequences of pipelines may be separated by `;', and are then executed
227 sequentially.
228 A sequence of pipelines may be executed without immediately
229 waiting for it to terminate by following it with an `\*[Am]'.
231 Any of the above may be placed in `(' `)' to form a simple command (that
232 may be a component of a pipeline, etc.).
233 It is also possible to separate pipelines with `\&|\&|'
234 or `\*[Am]\*[Am]' showing, as in the C language,
235 that the second is to be executed only if the first fails or succeeds
236 respectively.
237 (See
238 .Sx Expressions . )
239 .Ss Jobs
240 The shell associates a
241 .Ar job
242 with each pipeline.
243 It keeps
244 a table of current jobs, printed by the
245 .Ar jobs
246 command, and assigns them small integer numbers.
247 When a job is started asynchronously with `\*[Am]',
248 the shell prints a line that looks like:
249 .Bd -filled -offset indent
250 .Op 1
251 1234
254 showing that the job which was started asynchronously was job number
255 1 and had one (top-level) process, whose process id was 1234.
257 If you are running a job and wish to do something else you may hit the key
258 .Ic ^Z
259 (control-Z) which sends a STOP signal to the current job.
260 The shell will then normally show that the job has been `Stopped',
261 and print another prompt.
262 You can then manipulate the state of this job, putting it in the
263 .Em background
264 with the
265 .Ar bg
266 command, or run some other
267 commands and eventually bring the job back into the foreground with
269 .Em foreground
270 command
271 .Ar fg  .
273 .Ic ^Z
274 takes effect immediately and
275 is like an interrupt in that pending output and unread input are discarded
276 when it is typed.
277 There is another special key
278 .Ic ^Y
279 that does not generate a STOP signal until a program attempts to
280 .Xr read 2
282 This request can usefully be typed ahead when you have prepared some commands
283 for a job that you wish to stop after it has read them.
285 A job being run in the background will stop if it tries to read
286 from the terminal.
287 Background jobs are normally allowed to produce output,
288 but this can be disabled by giving the command ``stty tostop''.
289 If you set this
290 tty option, then background jobs will stop when they try to produce
291 output like they do when they try to read input.
293 There are several ways to refer to jobs in the shell.
294 The character `%' introduces a job name.
295 If you wish to refer to job number 1, you can name it as `%1'.
296 Just naming a job brings it to the foreground; thus
297 `%1' is a synonym for `fg %1', bringing job number 1 back into the foreground.
298 Similarly saying `%1 \*[Am]' resumes job number 1 in the background.
299 Jobs can also be named by prefixes of the string typed in to start them,
300 if these prefixes are unambiguous, thus `%ex' would normally restart
301 a suspended
302 .Xr ex 1
303 job, if there were only one suspended job whose name began with
304 the string `ex'.
305 It is also possible to say `%?string'
306 which specifies a job whose text contains
307 .Ar string ,
308 if there is only one such job.
310 The shell maintains a notion of the current and previous jobs.
311 In output about jobs, the current job is marked with a `+'
312 and the previous job with a `\-'.
313 The abbreviation `%+' refers
314 to the current job and `%\-' refers to the previous job.
315 For close analogy with the syntax of the
316 .Ar history
317 mechanism (described below),
318 `%%' is also a synonym for the current job.
320 The job control mechanism requires that the
321 .Xr stty 1
322 option
323 .Ic new
324 be set.
325 It is an artifact from a
326 .Em new
327 implementation
328 of the
329 tty driver that allows generation of interrupt characters from
330 the keyboard to tell jobs to stop.
332 .Xr stty 1
333 for details on setting options in the new tty driver.
334 .Ss Status reporting
335 The shell learns immediately whenever a process changes state.
336 It normally informs you whenever a job becomes blocked so that
337 no further progress is possible, but only just before it prints
338 a prompt.
339 This is done so that it does not otherwise disturb your work.
340 If, however, you set the shell variable
341 .Ar notify ,
342 the shell will notify you immediately of changes of status in background
343 jobs.
344 There is also a shell command
345 .Ar notify
346 that marks a single process so that its status changes will be immediately
347 reported.
348 By default
349 .Ar notify
350 marks the current process;
351 simply say `notify' after starting a background job to mark it.
353 When you try to leave the shell while jobs are stopped, you will
354 be warned that `You have stopped jobs.'
355 You may use the
356 .Ar jobs
357 command to see what they are.
358 If you try to exit again immediately,
359 the shell will not warn you a second time, and the suspended
360 jobs will be terminated.
361 .Ss File Name Completion
362 When the file name completion feature is enabled by setting
363 the shell variable
364 .Ar filec
365 (see
366 .Ic set ) ,
368 will
369 interactively complete file names and user names from unique
370 prefixes, when they are input from the terminal followed by
371 the escape character (the escape key, or control-[)
372 For example,
373 if the current directory looks like
374 .Bd -literal -offset indent
375 DSC.OLD  bin      cmd      lib      xmpl.c
376 DSC.NEW  chaosnet cmtest   mail     xmpl.o
377 bench    class    dev      mbox     xmpl.out
380 and the input is
382 .Dl % vi ch\*[Lt]escape\*[Gt]
385 will complete the prefix ``ch''
386 to the only matching file name ``chaosnet'', changing the input
387 line to
389 .Dl % vi chaosnet
391 However, given
393 .Dl % vi D\*[Lt]escape\*[Gt]
396 will only expand the input to
398 .Dl % vi DSC.
400 and will sound the terminal bell to indicate that the expansion is
401 incomplete, since there are two file names matching the prefix ``D''.
403 If a partial file name is followed by the end-of-file character
404 (usually control-D), then, instead of completing the name,
406 will list all file names matching the prefix.
407 For example,
408 the input
410 .Dl % vi D\*[Lt]control-D\*[Gt]
412 causes all files beginning with ``D'' to be listed:
414 .Dl DSC.NEW     DSC.OLD
416 while the input line remains unchanged.
418 The same system of escape and end-of-file can also be used to
419 expand partial user names, if the word to be completed
420 (or listed) begins with the character ``~''.
421 For example, typing
423 .Dl cd ~ro\*[Lt]escape\*[Gt]
425 may produce the expansion
427 .Dl cd ~root
429 The use of the terminal bell to signal errors or multiple matches
430 can be inhibited by setting the variable
431 .Ar nobeep  .
433 Normally, all files in the particular directory are candidates
434 for name completion.
435 Files with certain suffixes can be excluded
436 from consideration by setting the variable
437 .Ar fignore
438 to the
439 list of suffixes to be ignored.
440 Thus, if
441 .Ar fignore
442 is set by
443 the command
445 .Dl % set fignore = (.o .out)
447 then typing
449 .Dl % vi x\*[Lt]escape\*[Gt]
451 would result in the completion to
453 .Dl % vi xmpl.c
455 ignoring the files "xmpl.o" and "xmpl.out".
456 However, if the only completion possible requires not ignoring these
457 suffixes, then they are not ignored.
458 In addition,
459 .Ar fignore
460 does not affect the listing of file names by control-D.
461 All files
462 are listed regardless of their suffixes.
463 .Ss Substitutions
464 We now describe the various transformations the shell performs on the
465 input in the order in which they occur.
466 .Ss History substitutions
467 History substitutions place words from previous command input as portions
468 of new commands, making it easy to repeat commands, repeat arguments
469 of a previous command in the current command, or fix spelling mistakes
470 in the previous command with little typing and a high degree of confidence.
471 History substitutions begin with the character `!' and may begin
472 .Ar anywhere
473 in the input stream (with the proviso that they
474 .Em do not
475 nest.)
476 This `!' may be preceded by a `\e' to prevent its special meaning; for
477 convenience, an `!' is passed unchanged when it is followed by a blank,
478 tab, newline, `=' or `('.
479 (History substitutions also occur when an input line begins with `\*(ua'.
480 This special abbreviation will be described later.)
481 Any input line that contains history substitution is echoed on the terminal
482 before it is executed as it would have been typed without history substitution.
484 Commands input from the terminal that consist of one or more words
485 are saved on the history list.
486 The history substitutions reintroduce sequences of words from these
487 saved commands into the input stream.
488 The size of the history list is controlled by the
489 .Ar history
490 variable; the previous command is always retained,
491 regardless of the value of the history variable.
492 Commands are numbered sequentially from 1.
494 For example, consider the following output from the
495 .Ar history
496 command:
497 .Bd -literal -offset indent
498 09  write michael
499 10  ex write.c
500 11  cat oldwrite.c
501 12  diff *write.c
504 The commands are shown with their event numbers.
505 It is not usually necessary to use event numbers, but the current event
506 number can be made part of the
507 .Ar prompt
508 by placing an `!' in the prompt string.
510 With the current event 13 we can refer to previous events by event
511 number `!11', relatively as in `!\-2' (referring to the same event),
512 by a prefix of a command word
513 as in `!d' for event 12 or `!wri' for event 9, or by a string contained in
514 a word in the command as in `!?mic?' also referring to event 9.
515 These forms, without further change, simply reintroduce the words
516 of the specified events, each separated by a single blank.
517 As a special case, `!!' refers to the previous command; thus `!!' alone is a
518 .Ar redo .
520 To select words from an event we can follow the event specification by
521 a `:' and a designator for the desired words.
522 The words of an input line are numbered from 0,
523 the first (usually command) word being 0, the second word (first argument)
524 being 1, etc.
525 The basic word designators are:
527 .Bl -tag -width Ds -compact -offset indent
528 .It \&0
529 first (command) word
530 .It Ar n
531 .Ar n Ns 'th
532 argument
533 .It \*(ua
534 first argument,  i.e., `1'
535 .It $
536 last argument
537 .It %
538 word matched by (immediately preceding)
539 .No \&? Ns Ar s Ns \&?
540 search
541 .It Ar \&x\-y
542 range of words
543 .It Ar \&\-y
544 abbreviates
545 .Ar `\&0\-y\'
546 .It *
547 abbreviates `\*(ua\-$', or nothing if only 1 word in event
548 .It Ar x*
549 abbreviates
550 .Ar `x\-$\'
551 .It Ar x\-
552 like
553 .Ar `x*\'
554 but omitting word `$'
557 The `:' separating the event specification from the word designator
558 can be omitted if the argument selector begins with a `\*(ua', `$', `*',
559 `\-' or `%'.
560 After the optional word designator can be
561 placed a sequence of modifiers, each preceded by a `:'.
562 The following modifiers are defined:
564 .Bl -tag -width Ds -compact -offset indent
565 .It h
566 Remove a trailing pathname component, leaving the head.
567 .It r
568 Remove a trailing `.xxx' component, leaving the root name.
569 .It e
570 Remove all but the extension `.xxx' part.
571 .It s Ns Ar /l/r/
572 Substitute
573 .Ar l
575 .Ar r
576 .It t
577 Remove all leading pathname components, leaving the tail.
578 .It \&\*[Am]
579 Repeat the previous substitution.
580 .It g
581 Apply the change once on each word, prefixing the above, e.g., `g\*[Am]'.
582 .It a
583 Apply the change as many times as possible on a single word, prefixing
584 the above.
585 It can be used together with `g' to apply a substitution
586 globally.
587 .It p
588 Print the new command line but do not execute it.
589 .It q
590 Quote the substituted words, preventing further substitutions.
591 .It x
592 Like q, but break into words at blanks, tabs and newlines.
595 Unless preceded by a `g' the change is applied only to the first
596 modifiable word.
597 With substitutions, it is an error for no word to be applicable.
599 The left hand side of substitutions are not regular expressions in the sense
600 of the editors, but instead strings.
601 Any character may be used as the delimiter in place of `/';
602 a `\e' quotes the delimiter into the
603 .Ar l
605 .Ar r
606 strings.
607 The character `\*[Am]' in the right hand side is replaced by the text from
608 the left.
609 A `\e' also quotes `\*[Am]'.
610 A null
611 .Ar l
612 (`//')
613 uses the previous string either from an
614 .Ar l
615 or from a
616 contextual scan string
617 .Ar s
619 .No \&`!? Ns Ar s Ns \e?' .
620 The trailing delimiter in the substitution may be omitted if a newline
621 follows immediately as may the trailing `?' in a contextual scan.
623 A history reference may be given without an event specification, e.g., `!$'.
624 Here, the reference is to the previous command unless a previous
625 history reference occurred on the same line in which case this form repeats
626 the previous reference.
627 Thus `!?foo?\*(ua !$' gives the first and last arguments
628 from the command matching `?foo?'.
630 A special abbreviation of a history reference occurs when the first
631 non-blank character of an input line is a `\*(ua'.
632 This is equivalent to `!:s\*(ua' providing a convenient
633 shorthand for substitutions on the text of the previous line.
634 Thus `\*(ualb\*(ualib' fixes the spelling of
635 `lib'
636 in the previous command.
637 Finally, a history substitution may be surrounded with `{' and `}'
638 if necessary to insulate it from the characters that follow.
639 Thus, after `ls \-ld ~paul' we might do `!{l}a' to do `ls \-ld ~paula',
640 while `!la' would look for a command starting with `la'.
641 .Ss Quotations with \' and \&"
642 The quotation of strings by `\'' and `"' can be used
643 to prevent all or some of the remaining substitutions.
644 Strings enclosed in `\'' are prevented any further interpretation.
645 Strings enclosed in `"' may be expanded as described below.
647 In both cases the resulting text becomes (all or part of) a single word;
648 only in one special case (see
649 .Em Command Substitution
650 below) does a `"' quoted string yield parts of more than one word;
651 `\'' quoted strings never do.
652 .Ss Alias substitution
653 The shell maintains a list of aliases that can be established, displayed
654 and modified by the
655 .Ar alias
657 .Ar unalias
658 commands.
659 After a command line is scanned, it is parsed into distinct commands and
660 the first word of each command, left-to-right, is checked to see if it
661 has an alias.
662 If it does, then the text that is the alias for that command is reread
663 with the history mechanism available
664 as though that command were the previous input line.
665 The resulting words replace the
666 command and argument list.
667 If no reference is made to the history list, then the argument list is
668 left unchanged.
670 Thus if the alias for `ls' is `ls \-l' the command `ls /usr' would map to
671 `ls \-l /usr', the argument list here being undisturbed.
672 Similarly if the alias for `lookup' was `grep !\*(ua /etc/passwd' then
673 `lookup bill' would map to `grep bill /etc/passwd'.
675 If an alias is found, the word transformation of the input text
676 is performed and the aliasing process begins again on the reformed input line.
677 Looping is prevented if the first word of the new text is the same as the old
678 by flagging it to prevent further aliasing.
679 Other loops are detected and cause an error.
681 Note that the mechanism allows aliases to introduce parser metasyntax.
682 Thus, we can `alias print \'pr \e!* \&| lpr\'' to make a command that
683 .Ar pr Ns 's
684 its arguments to the line printer.
685 .Ss Variable substitution
686 The shell maintains a set of variables, each of which has as value a list
687 of zero or more words.
688 Some of these variables are set by the shell or referred to by it.
689 For instance, the
690 .Ar argv
691 variable is an image of the shell's argument list, and words of this
692 variable's value are referred to in special ways.
694 The values of variables may be displayed and changed by using the
695 .Ar set
697 .Ar unset
698 commands.
699 Of the variables referred to by the shell a number are toggles;
700 the shell does not care what their value is,
701 only whether they are set or not.
702 For instance, the
703 .Ar verbose
704 variable is a toggle that causes command input to be echoed.
705 The setting of this variable results from the
706 .Fl v
707 command line option.
709 Other operations treat variables numerically.
710 The `@' command permits numeric calculations to be performed and the result
711 assigned to a variable.
712 Variable values are, however, always represented as (zero or more) strings.
713 For the purposes of numeric operations, the null string is considered to be
714 zero, and the second and additional words of multiword values are ignored.
716 After the input line is aliased and parsed, and before each command
717 is executed, variable substitution
718 is performed keyed by `$' characters.
719 This expansion can be prevented by preceding the `$' with a `\e' except
720 within `"'s where it
721 .Em always
722 occurs, and within `\''s where it
723 .Em never
724 occurs.
725 Strings quoted by `\*(ga' are interpreted later (see
726 .Sx Command substitution
727 below), so `$' substitution does not occur there until later, if at all.
728 A `$' is passed unchanged if followed by a blank, tab, or end-of-line.
730 Input/output redirections are recognized before variable expansion,
731 and are variable expanded separately.
732 Otherwise, the command name and entire argument list are expanded together.
733 It is thus possible for the first (command) word (to this point) to generate
734 more than one word, the first of which becomes the command name,
735 and the rest of which become arguments.
737 Unless enclosed in `"' or given the `:q' modifier the results of variable
738 substitution may eventually be command and filename substituted.
739 Within `"', a variable whose value consists of multiple words expands to a
740 (portion of) a single word, with the words of the variable's value
741 separated by blanks.
742 When the `:q' modifier is applied to a substitution
743 the variable will expand to multiple words with each word separated
744 by a blank and quoted to prevent later command or filename substitution.
746 The following metasequences are provided for introducing variable values into
747 the shell input.
748 Except as noted, it is an error to reference a variable that is not set.
750 .Bl -tag -width Ds -compact -offset indent
751 .It $name
752 .It ${name}
753 Are replaced by the words of the value of variable
754 .Ar name ,
755 each separated by a blank.
756 Braces insulate
757 .Ar name
758 from following characters that would otherwise be part of it.
759 Shell variables have names consisting of up to 20 letters and digits
760 starting with a letter.
761 The underscore character is considered a letter.
763 .Ar name
764 is not a shell variable, but is set in the environment, then
765 that value is returned (but `:' modifiers and the other forms
766 given below are not available here).
767 .It $name Ns Op selector
768 .It ${name Ns [ selector ] Ns }
769 May be used to select only some of the words from the value of
770 .Ar name .
771 The selector is subjected to `$' substitution and may consist of a single
772 number or two numbers separated by a `\-'.
773 The first word of a variable's value is numbered `1'.
774 If the first number of a range is omitted it defaults to `1'.
775 If the last number of a range is omitted it defaults to `$#name'.
776 The selector `*' selects all words.
777 It is not an error for a range to be empty if the second argument is omitted
778 or in range.
779 .It $#name
780 .It ${#name}
781 Gives the number of words in the variable.
782 This is useful for later use in a
783 `$argv[selector]'.
784 .It $0
785 Substitutes the name of the file from which command input is being read.
786 An error occurs if the name is not known.
787 .It $number
788 .It ${number}
789 Equivalent to
790 `$argv[number]'.
791 .It $*
792 Equivalent to
793 `$argv[*]'.
796 The modifiers `:e', `:h', `:t', `:r', `:q' and `:x' may be applied to
797 the substitutions above as may `:gh', `:gt' and `:gr'.
798 If braces `{' '}' appear in the command form then the modifiers
799 must appear within the braces.
800 The current implementation allows only one `:' modifier on each `$' expansion.
802 The following substitutions may not be modified with `:' modifiers.
803 .Bl -tag -width Ds -compact -offset indent
804 .It $?name
805 .It ${?name}
806 Substitutes the string `1' if name is set, `0' if it is not.
807 .It $?0
808 Substitutes `1' if the current input filename is known, `0' if it is not.
809 .It \&$\&$\&
810 Substitute the (decimal) process number of the (parent) shell.
811 .It $!
812 Substitute the (decimal) process number of the last background process
813 started by this shell.
814 .It $\*[Lt]
815 Substitutes a line from the standard
816 input, with no further interpretation.
817 It can be used to read from the keyboard in a shell script.
819 .Ss Command and filename substitution
820 The remaining substitutions, command and filename substitution,
821 are applied selectively to the arguments of builtin commands.
822 By selectively, we mean that portions of expressions which are
823 not evaluated are not subjected to these expansions.
824 For commands that are not internal to the shell, the command
825 name is substituted separately from the argument list.
826 This occurs very late,
827 after input-output redirection is performed, and in a child
828 of the main shell.
829 .Ss Command substitution
830 Command substitution is shown by a command enclosed in `\*(ga'.
831 The output from such a command is normally broken into separate words
832 at blanks, tabs and newlines, with null words being discarded;
833 this text then replaces the original string.
834 Within `"'s, only newlines force new words; blanks and tabs are preserved.
836 In any case, the single final newline does not force a new word.
837 Note that it is thus possible for a command substitution to yield
838 only part of a word, even if the command outputs a complete line.
839 .Ss Filename substitution
840 If a word contains any of the characters `*', `?', `[' or `{'
841 or begins with the character `~', then that word is a candidate for
842 filename substitution, also known as `globbing'.
843 This word is then regarded as a pattern, and replaced with an alphabetically
844 sorted list of file names that match the pattern.
845 In a list of words specifying filename substitution it is an error for
846 no pattern to match an existing file name, but it is not required
847 for each pattern to match.
848 Only the metacharacters `*', `?' and `[' imply pattern matching,
849 the characters `~' and `{' being more akin to abbreviations.
851 In matching filenames, the character `.' at the beginning of a filename
852 or immediately following a `/', as well as the character `/' must
853 be matched explicitly.
854 The character `*' matches any string of characters, including the null
855 string.
856 The character `?' matches any single character.
857 The sequence
858 .Sq Op ...
859 matches any one of the characters enclosed.
860 Within
861 .Sq Op ... ,
862 a pair of characters separated by `\-' matches any character lexically between
863 the two (inclusive).
865 The character `~' at the beginning of a filename refers to home
866 directories.
867 Standing alone, i.e., `~' it expands to the invoker's home directory as reflected
868 in the value of the variable
869 .Ar home .
870 When followed by a name consisting of letters, digits and `\-' characters,
871 the shell searches for a user with that name and substitutes their
872 home directory;  thus `~ken' might expand to `/usr/ken' and `~ken/chmach'
873 to `/usr/ken/chmach'.
874 If the character `~' is followed by a character other than a letter or `/'
875 or does not appear at the beginning of a word,
876 it is left undisturbed.
878 The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'.
879 Left to right order is preserved, with results of matches being sorted
880 separately at a low level to preserve this order.
881 This construct may be nested.
882 Thus, `~source/s1/{oldls,ls}.c' expands to
883 `/usr/source/s1/oldls.c /usr/source/s1/ls.c'
884 without chance of error
885 if the home directory for `source' is `/usr/source'.
886 Similarly `../{memo,*box}' might expand to `../memo ../box ../mbox'.
887 (Note that `memo' was not sorted with the results of the match to `*box'.)
888 As a special case `{', `}' and `{}' are passed undisturbed.
889 .Ss Input/output
890 The standard input and the standard output of a command may be redirected
891 with the following syntax:
893 .Bl -tag -width Ds -compact -offset indent
894 .It \*[Lt] name
895 Open file
896 .Ar name
897 (which is first variable, command and filename expanded) as the standard
898 input.
899 .It \*[Lt]\*[Lt] word
900 Read the shell input up to a line that is identical to
901 .Ar word .
902 .Ar Word
903 is not subjected to variable, filename or command substitution,
904 and each input line is compared to
905 .Ar word
906 before any substitutions are done on the input line.
907 Unless a quoting `\e', `"', `\*(aa' or `\*(ga' appears in
908 .Ar word ,
909 variable and command substitution is performed on the intervening lines,
910 allowing `\e' to quote `$', `\e' and `\*(ga'.
911 Commands that are substituted have all blanks, tabs, and newlines
912 preserved, except for the final newline which is dropped.
913 The resultant text is placed in an anonymous temporary file that
914 is given to the command as its standard input.
915 .It \*[Gt] name
916 .It \*[Gt]! name
917 .It \*[Gt]\*[Am] name
918 .It \*[Gt]\*[Am]! name
919 The file
920 .Ar name
921 is used as the standard output.
922 If the file does not exist then it is created;
923 if the file exists, it is truncated; its previous contents are lost.
925 If the variable
926 .Ar noclobber
927 is set, then the file must not exist or be a character special file (e.g., a
928 terminal or `/dev/null') or an error results.
929 This helps prevent accidental destruction of files.
930 Here, the `!' forms can be used to suppress this check.
932 The forms involving `\*[Am]' route the standard error output into the specified
933 file as well as the standard output.
934 .Ar Name
935 is expanded in the same way as `\*[Lt]' input filenames are.
936 .It \*[Gt]\*[Gt] name
937 .It \*[Gt]\*[Gt]\*[Am] name
938 .It \*[Gt]\*[Gt]! name
939 .It \*[Gt]\*[Gt]\*[Am]! name
940 Uses file
941 .Ar name
942 as the standard output;
943 like `\*[Gt]' but places output at the end of the file.
944 If the variable
945 .Ar noclobber
946 is set, then it is an error for the file not to exist unless
947 one of the `!' forms is given.
948 Otherwise similar to `\*[Gt]'.
951 A command receives the environment in which the shell was
952 invoked as modified by the input-output parameters and
953 the presence of the command in a pipeline.
954 Thus, unlike some previous shells, commands run from a file of shell commands
955 have no access to the text of the commands by default;
956 instead they receive the original standard input of the shell.
957 The `\*[Lt]\*[Lt]' mechanism should be used to present inline data.
958 This permits shell command scripts to function as components of pipelines
959 and allows the shell to block read its input.
960 Note that the default standard input for a command run detached is
961 .Ar not
962 modified to be the empty file
963 .Pa /dev/null ;
964 instead the standard input
965 remains as the original standard input of the shell.
966 If this is a terminal
967 and if the process attempts to read from the terminal, then the process
968 will block and the user will be notified (see
969 .Sx Jobs
970 above).
972 The standard error output may be directed through
973 a pipe with the standard output.
974 Simply use the form `\&|\*[Am]' instead of just `\&|'.
975 .Ss Expressions
976 Several of the builtin commands (to be described later)
977 take expressions, in which the operators are similar to those of C, with
978 the same precedence, but with the
979 .Em opposite grouping :
980 right to left.
981 These expressions appear in the
982 .Ar @ ,
983 .Ar exit ,
984 .Ar if ,
986 .Ar while
987 commands.
988 The following operators are available:
989 .Bd -ragged -offset indent
990 \&|\&|  \*[Am]\*[Am]  \&| \*(ua  \*[Am]  ==  !=  =~  !~  \*[Le]  \*[Ge]
991 \*[Lt]  \*[Gt] \*[Lt]\*[Lt]  \*[Gt]\*[Gt]  +  \-  *  /  %  !  ~  (  )
994 Here the precedence increases to the right,
995 `==' `!=' `=~' and `!~', `\*[Le]' `\*[Ge]' `\*[Lt]'
996 and `\*[Gt]', `\*[Lt]\*[Lt]' and `\*[Gt]\*[Gt]', `+' and `\-',
997 `*' `/' and `%' being, in groups, at the same level.
998 The `==' `!=' `=~' and `!~' operators compare their arguments as strings;
999 all others operate on numbers.
1000 The operators `=~' and `!~' are like `!=' and `==' except that the right
1001 hand side is a
1002 .Ar pattern
1003 (containing, e.g., `*'s, `?'s and instances of `[...]')
1004 against which the left hand operand is matched.
1005 This reduces the need for use of the
1006 .Ar switch
1007 statement in shell scripts when all that is really needed is pattern matching.
1009 Strings that begin with `0' are considered octal numbers.
1010 Null or missing arguments are considered `0'.
1011 The result of all expressions are strings,
1012 which represent decimal numbers.
1013 It is important to note that no two components of an expression can appear
1014 in the same word; except when adjacent to components of expressions that
1015 are syntactically significant to the parser
1016 (`\*[Am]' `\&|' `\*[Lt]' `\*[Gt]' `(' `)'),
1017 they should be surrounded by spaces.
1019 Also available in expressions as primitive operands are command executions
1020 enclosed in `{' and `}'
1021 and file enquiries of the form
1022 .Fl l
1023 .Ar name
1024 where
1025 .Ic l
1026 is one of:
1027 .Bd -literal -offset indent
1028 r       read access
1029 w       write access
1030 x       execute access
1031 e       existence
1032 o       ownership
1033 z       zero size
1034 f       plain file
1035 d       directory
1038 The specified name is command and filename expanded and then tested
1039 to see if it has the specified relationship to the real user.
1040 If the file does not exist or is inaccessible then all enquiries return
1041 false, i.e., `0'.
1042 Command executions succeed, returning true, i.e., `1',
1043 if the command exits with status 0, otherwise they fail, returning
1044 false, i.e., `0'.
1045 If more detailed status information is required then the command
1046 should be executed outside an expression and the variable
1047 .Ar status
1048 examined.
1049 .Ss Control flow
1050 The shell contains several commands that can be used to regulate the
1051 flow of control in command files (shell scripts) and
1052 (in limited but useful ways) from terminal input.
1053 These commands all operate by forcing the shell to reread or skip in its
1054 input and, because of the implementation, restrict the placement of some
1055 of the commands.
1058 .Ic foreach ,
1059 .Ic switch ,
1061 .Ic while
1062 statements, as well as the
1063 .Ic if\-then\-else
1064 form of the
1065 .Ic if
1066 statement require that the major keywords appear in a single simple command
1067 on an input line as shown below.
1069 If the shell's input is not seekable,
1070 the shell buffers up input whenever a loop is being read
1071 and performs seeks in this internal buffer to accomplish the rereading
1072 implied by the loop.
1073 (To the extent that this allows, backward goto's will succeed on
1074 non-seekable inputs.)
1075 .Ss Builtin commands
1076 Builtin commands are executed within the shell.
1077 If a builtin command occurs as any component of a pipeline
1078 except the last then it is executed in a subshell.
1080 .Bl -tag -width Ds -compact -offset indent
1081 .It Ic alias
1082 .It Ic alias Ar name
1083 .It Ic alias Ar name wordlist
1084 The first form prints all aliases.
1085 The second form prints the alias for name.
1086 The final form assigns the specified
1087 .Ar wordlist
1088 as the alias of
1089 .Ar name ;
1090 .Ar wordlist
1091 is command and filename substituted.
1092 .Ar Name
1093 is not allowed to be
1094 .Ar alias
1096 .Ar unalias .
1098 .It Ic bg
1099 .It Ic bg \&% Ns Ar job ...
1100 Puts the current or specified jobs into the background, continuing them
1101 if they were stopped.
1103 .It Ic break
1104 Causes execution to resume after the
1105 .Ic end
1106 of the nearest enclosing
1107 .Ic foreach
1109 .Ic while .
1110 The remaining commands on the current line are executed.
1111 Multi-level breaks are thus possible by writing them all on one line.
1113 .It Ic breaksw
1114 Causes a break from a
1115 .Ic switch ,
1116 resuming after the
1117 .Ic endsw .
1119 .It Ic case Ar label :
1120 A label in a
1121 .Ic switch
1122 statement as discussed below.
1124 .It Ic cd
1125 .It Ic cd Ar name
1126 .It Ic chdir
1127 .It Ic chdir Ar name
1128 Change the shell's working directory to directory
1129 .Ar name .
1130 If no argument is given then change to the home directory of the user.
1132 .Ar name
1133 is not found as a subdirectory of the current directory (and does not begin
1134 with `/', `./' or `../'), then each
1135 component of the variable
1136 .Ic cdpath
1137 is checked to see if it has a subdirectory
1138 .Ar name .
1139 Finally, if all else fails but
1140 .Ar name
1141 is a shell variable whose value begins with `/', then this
1142 is tried to see if it is a directory.
1144 .It Ic continue
1145 Continue execution of the nearest enclosing
1146 .Ic while
1148 .Ic foreach .
1149 The rest of the commands on the current line are executed.
1151 .It Ic default :
1152 Labels the default case in a
1153 .Ic switch
1154 statement.
1155 The default should come after all
1156 .Ic case
1157 labels.
1159 .It Ic dirs
1160 Prints the directory stack; the top of the stack is at the left,
1161 the first directory in the stack being the current directory.
1163 .It Ic echo Ar  wordlist
1164 .It Ic echo Fl n Ar wordlist
1165 The specified words are written to the shell's standard output, separated
1166 by spaces, and terminated with a newline unless the
1167 .Fl n
1168 option is specified.
1170 .It Ic else
1171 .It Ic end
1172 .It Ic endif
1173 .It Ic endsw
1174 See the description of the
1175 .Ic foreach ,
1176 .Ic if ,
1177 .Ic switch ,
1179 .Ic while
1180 statements below.
1182 .It Ic eval Ar arg ...
1183 (As in
1184 .Xr sh 1 . )
1185 The arguments are read as input to the shell and the resulting
1186 command(s) executed in the context of the current shell.
1187 This is usually used to execute commands
1188 generated as the result of command or variable substitution, since
1189 parsing occurs before these substitutions.
1191 .Xr tset 1
1192 for an example of using
1193 .Ic eval .
1195 .It Ic exec Ar command
1196 The specified command is executed in place of the current shell.
1198 .It Ic exit
1199 .It Ic exit Ar ( expr )
1200 The shell exits either with the value of the
1201 .Ic status
1202 variable (first form) or with the value of the specified
1203 .Ic expr
1204 (second form).
1206 .It Ic fg
1207 .It Ic fg % Ns Ar job ...
1208 Brings the current or specified jobs into the foreground, continuing them if
1209 they were stopped.
1211 .It Ic foreach Ar name ( wordlist )
1212 .It ...
1213 .It Ic end
1214 The variable
1215 .Ic name
1216 is successively set to each member of
1217 .Ic wordlist
1218 and the sequence of commands between this command and the matching
1219 .Ic end
1220 are executed.
1221 (Both
1222 .Ic foreach
1224 .Ic end
1225 must appear alone on separate lines.)
1226 The builtin command
1227 .Ic continue
1228 may be used to continue the loop prematurely and the builtin
1229 command
1230 .Ic break
1231 to terminate it prematurely.
1232 When this command is read from the terminal, the loop is read once
1233 prompting with `?' before any statements in the loop are executed.
1234 If you make a mistake typing in a loop at the terminal you can rub it out.
1236 .It Ic glob Ar wordlist
1237 Like
1238 .Ic echo
1239 but no `\e' escapes are recognized and words are delimited
1240 by null characters in the output.
1241 Useful for programs that wish to use the shell to filename expand a list
1242 of words.
1244 .It Ic goto Ar word
1245 The specified
1246 .Ic word
1247 is filename and command expanded to yield a string of the form `label'.
1248 The shell rewinds its input as much as possible
1249 and searches for a line of the form `label:'
1250 possibly preceded by blanks or tabs.
1251 Execution continues after the specified line.
1253 .It Ic hashstat
1254 Print a statistics line showing how effective the internal hash
1255 table has been at locating commands (and avoiding
1256 .Ic exec Ns \'s ) .
1258 .Ic exec
1259 is attempted for each component of the
1260 .Em path
1261 where the hash function indicates a possible hit, and in each component
1262 that does not begin with a `/'.
1264 .It Ic history
1265 .It Ic history Ar n
1266 .It Ic history Fl r Ar n
1267 .It Ic history Fl h Ar n
1268 Displays the history event list; if
1269 .Ar n
1270 is given only the
1271 .Ar n
1272 most recent events are printed.
1274 .Fl r
1275 option reverses the order of printout to be most recent first
1276 instead of oldest first.
1278 .Fl h
1279 option causes the history list to be printed without leading numbers.
1280 This format produces files suitable for sourcing using the \-h
1281 option to
1282 .Ic source  .
1284 .It Ic if Ar ( expr ) No command
1285 If the specified expression evaluates true, then the single
1286 .Ar command
1287 with arguments is executed.
1288 Variable substitution on
1289 .Ar command
1290 happens early, at the same
1291 time it does for the rest of the
1292 .Ic if
1293 command.
1294 .Ar Command
1295 must be a simple command, not
1296 a pipeline, a command list, or a parenthesized command list.
1297 Input/output redirection occurs even if
1298 .Ar expr
1299 is false, i.e., when command is
1300 .Em not
1301 executed (this is a bug).
1303 .It Ic if Ar ( expr ) Ic then
1304 .It ...
1305 .It Ic else if Ar ( expr2 ) Ic then
1306 .It ...
1307 .It Ic else
1308 .It ...
1309 .It Ic endif
1310 If the specified
1311 .Ar expr
1312 is true then the commands up to the first
1313 .Ic else
1314 are executed; otherwise if
1315 .Ar expr2
1316 is true then the commands up to the
1317 second
1318 .Ic else
1319 are executed, etc.
1320 Any number of
1321 .Ic else-if
1322 pairs are possible; only one
1323 .Ic endif
1324 is needed.
1326 .Ic else
1327 part is likewise optional.
1328 (The words
1329 .Ic else
1331 .Ic endif
1332 must appear at the beginning of input lines;
1334 .Ic if
1335 must appear alone on its input line or after an
1336 .Ic else . )
1338 .It Ic jobs
1339 .It Ic jobs Fl l
1340 Lists the active jobs; the
1341 .Fl l
1342 option lists process id's in addition to the normal information.
1344 .It Ic kill % Ns Ar job
1345 .It Ic kill Ar pid ...
1346 .It Ic kill Fl l Op Ar exit_status
1347 .It Ic kill Fl s Ar signal_name pid ...
1348 .It Ic kill Fl Ar signal_name Ar pid ...
1349 .It Ic kill Fl Ar signal_number Ar pid ...
1350 Sends either the TERM (terminate) signal or the
1351 specified signal to the specified jobs or processes.
1352 Signals are either given by number or by names (as given in
1353 .In signal.h ,
1354 stripped of the prefix ``SIG'').
1355 The signal names are listed by ``kill \-l'';
1356 if an
1357 .Ar exit_status
1358 is specified, only the corresponding signal name will be written.
1359 There is no default, just saying `kill' does not
1360 send a signal to the current job.
1361 If the signal being sent is TERM (terminate) or HUP (hangup),
1362 then the job or process will be sent a CONT (continue) signal as well.
1364 .It Ic limit
1365 .It Ic limit Ar resource
1366 .It Ic limit Ar resource maximum-use
1367 .It Ic limit Fl h
1368 .It Ic limit Fl h Ar resource
1369 .It Ic limit Fl h Ar resource maximum-use
1370 Manipulates per-process system resource limits via the
1371 .Xr getrlimit 2
1373 .Xr setrlimit 2
1374 system calls; this
1375 limits the consumption by the current process and each process
1376 it creates to not individually exceed
1377 .Ar maximum-use
1378 on the
1379 specified
1380 .Ar resource  .
1381 If no
1382 .Ar maximum-use
1383 is given, then
1384 the current limit is printed; if no
1385 .Ar resource
1386 is given, then
1387 all limitations are given.
1389 If the
1390 .Fl h
1391 flag is given, the hard limits are used instead of the current
1392 limits.
1393 The hard limits impose a ceiling on the values of the current limits.
1394 Only the super-user may raise the hard limits,
1395 but a user may lower or raise the current limits within the legal range.
1397 Resources controllable currently include:
1398 .Bl -tag -width coredumpsize
1399 .It Ar cputime
1400 The maximum number of CPU-seconds to be used by each process.
1401 .It Ar filesize
1402 The largest single file (in bytes) that can be created.
1403 .It Ar datasize
1404 The maximum growth of the data+stack region via
1405 .Xr sbrk 2
1406 beyond the end of the program text.
1407 .It Ar stacksize
1408 The maximum
1409 size of the automatically-extended stack region.
1410 .It Ar coredumpsize
1411 The size of the largest core dump (in bytes) that will be created.
1412 .It Ar memoryuse
1413 The maximum size (in bytes) to which a process's resident set
1414 size (RSS) may grow.
1415 .It Ar memorylocked
1416 The maximum size (in bytes) which a process may lock into memory using the
1417 .Xr mlock 2
1418 function.
1419 .It Ar maxproc
1420 The maximum number of simultaneous processes for this user id.
1421 .It Ar openfiles
1422 The maximum number of simultaneous open files for this user id.
1423 .It Ar sbsize
1424 The maximum socket buffer size of a process (in bytes).
1425 .It Ar vmemoryuse
1426 The maximum size (in bytes) which a process can obtain.
1430 .Ar maximum-use
1431 may be given as a (floating point or integer)
1432 number followed by a scale factor.
1433 For all limits other than
1434 .Ar cputime
1435 the default scale is `k' or `kilobytes' (1024 bytes);
1436 a scale factor of `m' or `megabytes' may also be used.
1438 .Ar cputime
1439 the default scale is `seconds';
1440 a scale factor of `m' for minutes
1441 or `h' for hours, or a time of the form `mm:ss' giving minutes
1442 and seconds also may be used.
1444 For both
1445 .Ar resource
1446 names and scale factors, unambiguous prefixes
1447 of the names suffice.
1449 Limits of an arbitrary process can be displayed or set using the
1450 .Xr sysctl 8
1451 utility.
1452 See the
1453 .Xr getrlimit 2
1455 .Xr setrlimit 2
1456 man pages for an additional description of system resource limits.
1458 .It Ic login
1459 Terminate a login shell, replacing it with an instance of
1460 .Pa /usr/bin/login .
1461 This is one way to log off, included for compatibility with
1462 .Xr sh 1 .
1464 .It Ic logout
1465 Terminate a login shell.
1466 Especially useful if
1467 .Ic ignoreeof
1468 is set.
1470 .It Ic nice
1471 .It Ic nice Ar +number
1472 .It Ic nice Ar command
1473 .It Ic nice Ar +number command
1474 The first form sets the
1475 scheduling priority
1476 for this shell to 4.
1477 The second form sets the
1478 priority
1479 to the given
1480 .Ar number .
1481 The final two forms run command at priority 4 and
1482 .Ar number
1483 respectively.
1484 The greater the number, the less CPU the process will get.
1485 The super-user may specify negative priority by using `nice \-number ...'.
1486 .Ar Command
1487 is always executed in a sub-shell, and the restrictions
1488 placed on commands in simple
1489 .Ic if
1490 statements apply.
1492 .It Ic nohup
1493 .It Ic nohup Ar command
1494 The first form can be used in shell scripts to cause hangups to be
1495 ignored for the remainder of the script.
1496 The second form causes the specified command to be run with hangups
1497 ignored.
1498 All processes detached with `\*[Am]' are effectively
1499 .Ic nohup Ns \'ed .
1501 .It Ic notify
1502 .It Ic notify % Ns Ar job ...
1503 Causes the shell to notify the user asynchronously when the status of the
1504 current or specified jobs change; normally notification is presented
1505 before a prompt.
1506 This is automatic if the shell variable
1507 .Ic notify
1508 is set.
1510 .It Ic onintr
1511 .It Ic onintr Fl
1512 .It Ic onintr Ar label
1513 Control the action of the shell on interrupts.
1514 The first form restores the default action of the shell on interrupts
1515 which is to terminate shell scripts or to return to the terminal command
1516 input level.
1517 The second form `onintr \-' causes all interrupts to be ignored.
1518 The final form causes the shell to execute a `goto label' when
1519 an interrupt is received or a child process terminates because
1520 it was interrupted.
1522 In any case, if the shell is running detached and interrupts are
1523 being ignored, all forms of
1524 .Ic onintr
1525 have no meaning and interrupts
1526 continue to be ignored by the shell and all invoked commands.
1527 Finally
1528 .Ic onintr
1529 statements are ignored in the system startup files where interrupts
1530 are disabled (/etc/csh.cshrc, /etc/csh.login).
1532 .It Ic popd
1533 .It Ic popd Ar +n
1534 Pops the directory stack, returning to the new top directory.
1535 With an argument
1536 .Ns \`+ Ar n Ns \'
1537 discards the
1538 .Ar n Ns \'th
1539 entry in the stack.
1540 The members of the directory stack are numbered from the top starting at 0.
1542 .It Ic pushd
1543 .It Ic pushd Ar name
1544 .It Ic pushd Ar +n
1545 With no arguments,
1546 .Ic pushd
1547 exchanges the top two elements of the directory stack.
1548 Given a
1549 .Ar name
1550 argument,
1551 .Ic pushd
1552 changes to the new directory (ala
1553 .Ic cd )
1554 and pushes the old current working directory
1555 (as in
1556 .Ic cwd )
1557 onto the directory stack.
1558 With a numeric argument,
1559 .Ic pushd
1560 rotates the
1561 .Ar n Ns \'th
1562 argument of the directory
1563 stack around to be the top element and changes to it.
1564 The members
1565 of the directory stack are numbered from the top starting at 0.
1567 .It Ic rehash
1568 Causes the internal hash table of the contents of the directories in
1570 .Ic path
1571 variable to be recomputed.
1572 This is needed if new commands are added to directories in the
1573 .Ic path
1574 while you are logged in.
1575 This should only be necessary if you add
1576 commands to one of your own directories, or if a systems programmer
1577 changes the contents of a system directory.
1579 .It Ic repeat Ar count command
1580 The specified
1581 .Ar command ,
1582 which is subject to the same restrictions
1583 as the
1584 .Ar command
1585 in the one line
1586 .Ic if
1587 statement above,
1588 is executed
1589 .Ar count
1590 times.
1591 I/O redirections occur exactly once, even if
1592 .Ar count
1593 is 0.
1595 .It Ic set
1596 .It Ic set Ar name
1597 .It Ic set Ar name Ns =word
1598 .It Ic set Ar name[index] Ns =word
1599 .It Ic set Ar name Ns =(wordlist)
1600 The first form of the command shows the value of all shell variables.
1601 Variables that have other than a single word as their
1602 value print as a parenthesized word list.
1603 The second form sets
1604 .Ar name
1605 to the null string.
1606 The third form sets
1607 .Ar name
1608 to the single
1609 .Ar word .
1610 The fourth form sets
1612 .Ar index Ns 'th
1613 component of
1614 .Ar name
1616 .Ar word ;
1617 this component must already exist.
1618 The final form sets
1619 .Ar name
1620 to the list of words in
1621 .Ar wordlist .
1622 The value is always command and filename expanded.
1624 These arguments may be repeated to set multiple values in a single set command.
1625 Note however, that variable expansion happens for all arguments before any
1626 setting occurs.
1628 .It Ic setenv
1629 .It Ic setenv Ar name
1630 .It Ic setenv Ar name value
1631 The first form lists all current environment variables.
1632 It is equivalent to
1633 .Xr printenv 1 .
1634 The last form sets the value of environment variable
1635 .Ar name
1636 to be
1637 .Ar value ,
1638 a single string.
1639 The second form sets
1640 .Ar name
1641 to an empty string.
1642 The most commonly used environment variables
1643 .Ev USER ,
1644 .Ev TERM ,
1646 .Ev PATH
1647 are automatically imported to and exported from the
1649 variables
1650 .Ar user ,
1651 .Ar term ,
1653 .Ar path ;
1654 there is no need to use
1655 .Ic setenv
1656 for these.
1658 .It Ic shift
1659 .It Ic shift Ar variable
1660 The members of
1661 .Ic argv
1662 are shifted to the left, discarding
1663 .Ic argv Ns Bq 1 .
1664 It is an error for
1665 .Ic argv
1666 not to be set or to have less than one word as value.
1667 The second form performs the same function on the specified variable.
1669 .It Ic source Ar name
1670 .It Ic source Fl h Ar name
1671 The shell reads commands from
1672 .Ar name .
1673 .Ic Source
1674 commands may be nested; if they are nested too deeply the shell may
1675 run out of file descriptors.
1676 An error in a
1677 .Ic source
1678 at any level terminates all nested
1679 .Ic source
1680 commands.
1681 Normally input during
1682 .Ic source
1683 commands is not placed on the history list;
1684 the \-h option causes the commands to be placed on the
1685 history list without being executed.
1687 .It Ic stop
1688 .It Ic stop % Ns Ar job ...
1689 Stops the current or specified jobs that are executing in the background.
1691 .It Ic suspend
1692 Causes the shell to stop in its tracks, much as if it had been sent a stop
1693 signal with
1694 .Ic ^Z .
1695 This is most often used to stop shells started by
1696 .Xr su 1 .
1698 .It Ic switch Ar ( string )
1699 .It Ic case Ar str1 :
1700 .It \ \ \ \ \&...
1701 .It Ic \ \ \ \ breaksw
1702 .It \ \ \ \ \&...
1703 .It Ic default :
1704 .It \ \ \ \ \&...
1705 .It Ic \ \ \ \ breaksw
1706 .It Ic endsw
1707 Each case label is successively matched against the specified
1708 .Ar string
1709 which is first command and filename expanded.
1710 The file metacharacters `*', `?' and `[...]'
1711 may be used in the case labels,
1712 which are variable expanded.
1713 If none of the labels match before the `default' label is found, then
1714 the execution begins after the default label.
1715 Each case label and the default label must appear at the beginning of a line.
1716 The command
1717 .Ic breaksw
1718 causes execution to continue after the
1719 .Ic endsw .
1720 Otherwise control may fall through case labels and the default label as in C.
1721 If no label matches and there is no default, execution continues after
1723 .Ic endsw .
1725 .It Ic time
1726 .It Ic time Ar command
1727 With no argument, a summary of time used by this shell and its children
1728 is printed.
1729 If arguments are given
1730 the specified simple command is timed and a time summary
1731 as described under the
1732 .Ic time
1733 variable is printed.
1734 If necessary, an extra shell is created to print the time
1735 statistic when the command completes.
1737 .It Ic umask
1738 .It Ic umask Ar value
1739 The file creation mask is displayed (first form) or set to the specified
1740 value (second form).
1741 The mask is given in octal.
1742 Common values for
1743 the mask are 002 giving all access to the group and read and execute
1744 access to others or 022 giving all access except write access for
1745 users in the group or others.
1747 .It Ic unalias Ar pattern
1748 All aliases whose names match the specified pattern are discarded.
1749 Thus all aliases are removed by `unalias *'.
1750 It is not an error for nothing to be
1751 .Ic unaliased .
1753 .It Ic unhash
1754 Use of the internal hash table to speed location of executed programs
1755 is disabled.
1757 .It Ic unlimit
1758 .It Ic unlimit Ar  resource
1759 .It Ic unlimit Fl h
1760 .It Ic unlimit Fl h Ar resource
1761 Removes the limitation on
1762 .Ar resource  .
1763 If no
1764 .Ar resource
1765 is specified, then all
1766 .Ar resource
1767 limitations are removed.
1769 .Fl h
1770 is given, the corresponding hard limits are removed.
1771 Only the
1772 super-user may do this.
1774 .It Ic unset Ar pattern
1775 All variables whose names match the specified pattern are removed.
1776 Thus all variables are removed by `unset *'; this has noticeably
1777 distasteful side-effects.
1778 It is not an error for nothing to be
1779 .Ic unset .
1781 .It Ic unsetenv Ar pattern
1782 Removes all variables whose name match the specified pattern from the
1783 environment.
1784 See also the
1785 .Ic setenv
1786 command above and
1787 .Xr printenv 1 .
1789 .It Ic wait
1790 Wait for all background jobs.
1791 If the shell is interactive, then an interrupt can disrupt the wait.
1792 After the interrupt, the shell prints names and job numbers of all jobs
1793 known to be outstanding.
1795 .It Ic which Ar command
1796 Displays the resolved command that will be executed by the shell.
1798 .It Ic while Ar ( expr )
1799 .It \&...
1800 .It Ic end
1801 While the specified expression evaluates non-zero, the commands between
1803 .Ic while
1804 and the matching
1805 .Ic end
1806 are evaluated.
1807 .Ic Break
1809 .Ic continue
1810 may be used to terminate or continue the loop prematurely.
1811 (The
1812 .Ic while
1814 .Ic end
1815 must appear alone on their input lines.)
1816 Prompting occurs here the first time through the loop as for the
1817 .Ic foreach
1818 statement if the input is a terminal.
1820 .It Ic % Ns Ar job
1821 Brings the specified job into the foreground.
1823 .It Ic % Ns Ar job Ic \*[Am]
1824 Continues the specified job in the background.
1826 .It Ic @
1827 .It Ic @ Ar name Ns = expr
1828 .It Ic @ Ar name[index] Ns = expr
1829 The first form prints the values of all the shell variables.
1830 The second form sets the specified
1831 .Ar name
1832 to the value of
1833 .Ar expr .
1834 If the expression contains `\*[Lt]', `\*[Gt]', `\*[Am]' or `|' then at least
1835 this part of the expression must be placed within `(' `)'.
1836 The third form assigns the value of
1837 .Ar expr
1838 to the
1839 .Ar index Ns 'th
1840 argument of
1841 .Ar name .
1842 Both
1843 .Ar name
1844 and its
1845 .Ar index Ns 'th
1846 component must already exist.
1849 The operators `*=', `+=', etc are available as in C.
1850 The space separating the name from the assignment operator is optional.
1851 Spaces are, however, mandatory in separating components of
1852 .Ar expr
1853 which would otherwise be single words.
1855 Special postfix `+\|+' and `\-\|\-' operators increment and decrement
1856 .Ar name
1857 respectively, i.e., `@  i++'.
1858 .Ss Pre-defined and environment variables
1859 The following variables have special meaning to the shell.
1860 Of these,
1861 .Ar argv ,
1862 .Ar cwd ,
1863 .Ar home ,
1864 .Ar path ,
1865 .Ar prompt ,
1866 .Ar shell
1868 .Ar status
1869 are always set by the shell.
1870 Except for
1871 .Ar cwd
1873 .Ar status ,
1874 this setting occurs only at initialization;
1875 these variables will not then be modified unless done
1876 explicitly by the user.
1878 The shell copies the environment variable
1879 .Ev USER
1880 into the variable
1881 .Ar user ,
1882 .Ev TERM
1883 into
1884 .Ar term ,
1886 .Ev HOME
1887 into
1888 .Ar home ,
1889 and copies these back into the environment whenever the normal
1890 shell variables are reset.
1891 The environment variable
1892 .Ev PATH
1893 is likewise handled; it is not
1894 necessary to worry about its setting other than in the file
1895 .Ar \&.cshrc
1896 as inferior
1898 processes will import the definition of
1899 .Ar path
1900 from the environment, and re-export it if you then change it.
1901 .Bl -tag -width histchars
1902 .It Ic argv
1903 Set to the arguments to the shell, it is from this variable that
1904 positional parameters are substituted, i.e., `$1' is replaced by
1905 `$argv[1]',
1906 etc.
1907 .It Ic cdpath
1908 Gives a list of alternative directories searched to find subdirectories
1910 .Ar chdir
1911 commands.
1912 .It Ic cwd
1913 The full pathname of the current directory.
1914 .It Ic echo
1915 Set when the
1916 .Fl x
1917 command line option is given.
1918 Causes each command and its arguments
1919 to be echoed just before it is executed.
1920 For non-builtin commands all expansions occur before echoing.
1921 Builtin commands are echoed before command and filename substitution,
1922 since these substitutions are then done selectively.
1923 .It Ic filec
1924 Enable file name completion.
1925 .It Ic histchars
1926 Can be given a string value to change the characters used in history
1927 substitution.
1928 The first character of its value is used as the
1929 history substitution character, replacing the default character `!'.
1930 The second character of its value replaces the character `^' in
1931 quick substitutions.
1932 .It Ic histfile
1933 Can be set to the pathname where history is going to be saved/restored.
1934 .It Ic history
1935 Can be given a numeric value to control the size of the history list.
1936 Any command that has been referenced in this many events will not be
1937 discarded.
1938 Too large values of
1939 .Ar history
1940 may run the shell out of memory.
1941 The last executed command is always saved on the history list.
1942 .It Ic home
1943 The home directory of the invoker, initialized from the environment.
1944 The filename expansion of
1945 .Sq Pa ~
1946 refers to this variable.
1947 .It Ic ignoreeof
1948 If set the shell ignores
1949 end-of-file from input devices which are terminals.
1950 This prevents shells from accidentally being killed by control-D's.
1951 .It Ic mail
1952 The files where the shell checks for mail.
1953 This checking is done after each command completion that will
1954 result in a prompt,
1955 if a specified interval has elapsed.
1956 The shell says `You have new mail.'
1957 if the file exists with an access time not greater than its modify time.
1959 If the first word of the value of
1960 .Ar mail
1961 is numeric it specifies a different mail checking interval, in seconds,
1962 than the default, which is 10 minutes.
1964 If multiple mail files are specified, then the shell says
1965 `New mail in
1966 .Ar name Ns '
1967 when there is mail in the file
1968 .Ar name .
1969 .It Ic noclobber
1970 As described in the section on
1971 .Sx Input/output ,
1972 restrictions are placed on output redirection to ensure that
1973 files are not accidentally destroyed, and that `\*[Gt]\*[Gt]' redirections
1974 refer to existing files.
1975 .It Ic noglob
1976 If set, filename expansion is inhibited.
1977 This inhibition is most useful in shell scripts that
1978  are not dealing with filenames,
1979 or after a list of filenames has been obtained and further expansions
1980 are not desirable.
1981 .It Ic nonomatch
1982 If set, it is not an error for a filename expansion to not match any
1983 existing files; instead the primitive pattern is returned.
1984 It is still an error for the primitive pattern to be malformed, i.e.,
1985 `echo ['
1986 still gives an error.
1987 .It Ic notify
1988 If set, the shell notifies asynchronously of job completions;
1989 the default is to present job completions just before printing
1990 a prompt.
1991 .It Ic path
1992 Each word of the path variable specifies a directory in which
1993 commands are to be sought for execution.
1994 A null word specifies the current directory.
1995 If there is no
1996 .Ar path
1997 variable then only full path names will execute.
1998 The usual search path is `.', `/bin' and `/usr/bin', but this
1999 may vary from system to system.
2000 For the super-user the default search path is `/etc', `/bin' and `/usr/bin'.
2001 A shell that is given neither the
2002 .Fl c
2003 nor the
2004 .Fl t
2005 option will normally hash the contents of the directories in the
2006 .Ar path
2007 variable after reading
2008 .Ar \&.cshrc ,
2009 and each time the
2010 .Ar path
2011 variable is reset.
2012 If new commands are added to these directories
2013 while the shell is active, it may be necessary to do a
2014 .Ic rehash
2015 or the commands may not be found.
2016 .It Ic prompt
2017 The string that is printed before each command is read from
2018 an interactive terminal input.
2019 If a `!' appears in the string it will be replaced by the current event number
2020 unless a preceding `\e' is given.
2021 Default is `% ', or `# ' for the super-user.
2022 .It Ic savehist
2023 Is given a numeric value to control the number of entries of the
2024 history list that are saved in ~/.history when the user logs out.
2025 Any command that has been referenced in this many events will be saved.
2026 During start up the shell sources ~/.history into the history list
2027 enabling history to be saved across logins.
2028 Too large values of
2029 .Ar savehist
2030 will slow down the shell during start up.
2032 .Ar savehist
2033 is just set, the shell will use the value of
2034 .Ar history .
2035 .It Ic shell
2036 The file in which the shell resides.
2037 This variable is used in forking shells to interpret files that have execute
2038 bits set, but which are not executable by the system.
2039 (See the description of
2040 .Sx Non-builtin command execution
2041 below.)
2042 Initialized to the (system-dependent) home of the shell.
2043 .It Ic status
2044 The status returned by the last command.
2045 If it terminated abnormally, then 0200 is added to the status.
2046 Builtin commands that fail return exit status `1',
2047 all other builtin commands set status to `0'.
2048 .It Ic time
2049 Controls automatic timing of commands.
2050 This setting allows two parameters.
2051 The first specifies the CPU time threshold at which reporting should be done
2052 for a process, and the optional second specifies the output format.
2053 The following format strings are available:
2055 .Bl -tag -width Ds -compact -offset indent
2056 .It Li \&%c
2057 Number of involuntary context switches.
2058 .It Li \&%D
2059 Average unshared data size.
2060 .It Li \&%E
2061 Elapsed (wall\-clock) time.
2062 .It Li \&%F
2063 Page faults.
2064 .It Li \&%I
2065 Filesystem blocks in.
2066 .It Li \&%K
2067 Average total data memory used.
2068 .It Li \&%k
2069 Number of signals received.
2070 .It Li \&%M
2071 Maximum Resident Set Size.
2072 .It Li \&%O
2073 Filesystem blocks out.
2074 .It Li \&%P
2075 Total percent time spent running.
2076 .It Li \&%R
2077 Page reclaims.
2078 .It Li \&%r
2079 Socket messages received.
2080 .It Li \&%S
2081 Total system CPU time used.
2082 .It Li \&%s
2083 Socket messages sent.
2084 .It Li \&%U
2085 Total user CPU time used.
2086 .It Li \&%W
2087 Number of swaps.
2088 .It Li \&%w
2089 Number of voluntary context switches (waits).
2090 .It Li \&%X
2091 Average shared text size.
2094 The default summary is "%Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww"
2095 .It Ic verbose
2096 Set by the
2097 .Fl v
2098 command line option, causes the words of each command to be printed
2099 after history substitution.
2101 .Ss Non-builtin command execution
2102 When a command to be executed is found to not be a builtin command
2103 the shell attempts to execute the command via
2104 .Xr execve 2 .
2105 Each word in the variable
2106 .Ar path
2107 names a directory from which the shell will attempt to execute the command.
2108 If it is given neither a
2109 .Fl c
2110 nor a
2111 .Fl t
2112 option, the shell will hash the names in these directories into an internal
2113 table so that it will only try an
2114 .Ic exec
2115 in a directory if there is a possibility that the command resides there.
2116 This shortcut greatly speeds command location when many directories
2117 are present in the search path.
2118 If this mechanism has been turned off (via
2119 .Ic unhash ) ,
2120 or if the shell was given a
2121 .Fl c
2123 .Fl t
2124 argument, and in any case for each directory component of
2125 .Ar path
2126 that does not begin with a `/',
2127 the shell concatenates with the given command name to form a path name
2128 of a file which it then attempts to execute.
2130 Parenthesized commands are always executed in a subshell.
2131 Thus
2133 .Dl (cd ; pwd) ; pwd
2135 prints the
2136 .Ar home
2137 directory; leaving you where you were (printing this after the home directory),
2138 while
2140 .Dl cd ; pwd
2142 leaves you in the
2143 .Ar home
2144 directory.
2145 Parenthesized commands are most often used to prevent
2146 .Ic chdir
2147 from affecting the current shell.
2149 If the file has execute permissions but is not an
2150 executable binary to the system, then it is assumed to be a
2151 file containing shell commands and a new shell is spawned to read it.
2153 If there is an
2154 .Ic alias
2156 .Ic shell
2157 then the words of the alias will be prepended to the argument list to form
2158 the shell command.
2159 The first word of the
2160 .Ic alias
2161 should be the full path name of the shell
2162 (e.g., `$shell').
2163 Note that this is a special, late occurring, case of
2164 .Ic alias
2165 substitution,
2166 and only allows words to be prepended to the argument list without change.
2167 .Ss Signal handling
2168 The shell normally ignores
2169 .Ar quit
2170 signals.
2171 Jobs running detached (either by
2172 .Ic \&\*[Am]
2173 or the
2174 .Ic bg
2176 .Ic %... \*[Am]
2177 commands) are immune to signals generated from the keyboard, including
2178 hangups.
2179 Other signals have the values which the shell inherited from its parent.
2180 The shell's handling of interrupts and terminate signals
2181 in shell scripts can be controlled by
2182 .Ic onintr .
2183 Login shells catch the
2184 .Ar terminate
2185 signal; otherwise this signal is passed on to children from the state in the
2186 shell's parent.
2187 Interrupts are not allowed when a login shell is reading the file
2188 .Pa \&.logout .
2189 .Sh FILES
2190 .Bl -tag -width /etc/passwd -compact
2191 .It Pa ~/.cshrc
2192 Read at beginning of execution by each shell.
2193 .It Pa ~/.login
2194 Read by login shell, after `.cshrc' at login.
2195 .It Pa ~/.logout
2196 Read by login shell, at logout.
2197 .It Pa /bin/sh
2198 Standard shell, for shell scripts not starting with a `#'.
2199 .It Pa /tmp/sh*
2200 Temporary file for `\*[Lt]\*[Lt]'.
2201 .It Pa /etc/passwd
2202 Source of home directories for `~name'.
2204 .Sh LIMITATIONS
2205 Word lengths \-
2206 Words can be no longer than 1024 characters.
2207 The system limits argument lists to 10240 characters.
2208 The number of arguments to a command that involves filename expansion
2209 is limited to 1/6'th the number of characters allowed in an argument list.
2210 Command substitutions may substitute no more characters than are
2211 allowed in an argument list.
2212 To detect looping, the shell restricts the number of
2213 .Ic alias
2214 substitutions on a single line to 20.
2215 .Sh SEE ALSO
2216 .Xr sh 1 ,
2217 .Xr access 2 ,
2218 .Xr execve 2 ,
2219 .Xr fork 2 ,
2220 .Xr pipe 2 ,
2221 .Xr setrlimit 2 ,
2222 .Xr sigaction 2 ,
2223 .Xr umask 2 ,
2224 .Xr wait 2 ,
2225 .Xr killpg 3 ,
2226 .Xr tty 4 ,
2227 .Xr a.out 5 ,
2228 .Xr environ 7 ,
2229 .Xr sysctl 8
2231 .%T "An introduction to the C shell"
2233 .Sh HISTORY
2235 appeared in
2236 .Bx 2 .
2237 It was a first implementation of a command language interpreter
2238 incorporating a history mechanism (see
2239 .Sx History substitutions ) ,
2240 job control facilities (see
2241 .Sx Jobs ) ,
2242 interactive file name
2243 and user name completion (see
2244 .Sx File Name Completion ) ,
2245 and a C-like syntax.
2246 There are now many shells that also have these mechanisms, plus
2247 a few more (and maybe some bugs too), which are available through the
2248 usenet.
2249 .Sh AUTHORS
2250 William Joy.
2251 Job control and directory stack features first implemented by J.E. Kulp of
2252 IIASA, Laxenburg, Austria,
2253 with different syntax than that used now.
2254 File name completion code written by Ken Greer, HP Labs.
2255 Eight-bit implementation Christos S. Zoulas, Cornell University.
2256 .Sh BUGS
2257 When a command is restarted from a stop,
2258 the shell prints the directory it started in if this is different
2259 from the current directory; this can be misleading (i.e., wrong)
2260 as the job may have changed directories internally.
2262 Shell builtin functions are not stoppable/restartable.
2263 Command sequences of the form `a ; b ; c' are also not handled gracefully
2264 when stopping is attempted.
2265 If you suspend `b', the shell will immediately execute `c'.
2266 This is especially noticeable if this expansion results from an
2267 .Ar alias .
2268 It suffices to place the sequence of commands in ()'s to force it to
2269 a subshell, i.e., `( a ; b ; c )'.
2271 Control over tty output after processes are started is primitive;
2272 perhaps this will inspire someone to work on a good virtual
2273 terminal interface.
2274 In a virtual terminal interface much more
2275 interesting things could be done with output control.
2277 Alias substitution is most often used to clumsily simulate shell procedures;
2278 shell procedures should be provided instead of aliases.
2280 Commands within loops, prompted for by `?', are not placed on the
2281 .Ic history
2282 list.
2283 Control structure should be parsed instead of being recognized as built-in
2284 commands.
2285 This would allow control commands to be placed anywhere,
2286 to be combined with `\&|', and to be used with `\*[Am]' and `;' metasyntax.
2288 It should be possible to use the `:' modifiers on the output of command
2289 substitutions.
2291 The way the
2292 .Ic filec
2293 facility is implemented is ugly and expensive.