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