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