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