| blob | 76ee1ebd5d17f13b2f100dbc72c83d614b8c3bae |
1 .\"-
2 .\" Copyright (c) 1980, 1993
3 .\" The Regents of the University of California. All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 4. Neither the name of the University nor the names of its contributors
14 .\" may be used to endorse or promote products derived from this software
15 .\" without specific prior written permission.
16 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" SUCH DAMAGE.
28 .\"
29 .\" @(#)csh.3 8.1 (Berkeley) 6/8/93
30 .\" $FreeBSD$
31 .\"
32 .nr H1 2
33 .NH
34 Shell control structures and command scripts
35 .NH 2
36 Introduction
37 .PP
38 It is possible to place commands in files and to cause shells to be
39 invoked to read and execute commands from these files,
40 which are called
41 .I "shell scripts."
42 We here detail those features of the shell useful to the writers of such
43 scripts.
44 .NH 2
45 Make
46 .PP
47 It is important to first note what shell scripts are
48 .I not
49 useful for.
50 There is a program called
51 .I make
52 which is very useful for maintaining a group of related files
53 or performing sets of operations on related files.
54 For instance a large program consisting of one or more files
55 can have its dependencies described in a
56 .I makefile
57 which contains definitions of the commands used to create these
58 different files when changes occur.
59 Definitions of the means for printing listings, cleaning up the directory
60 in which the files reside, and installing the resultant programs
61 are easily, and most appropriately placed in this
62 .I makefile.
63 This format is superior and preferable to maintaining a group of shell
64 procedures to maintain these files.
65 .PP
66 Similarly when working on a document a
67 .I makefile
68 may be created which defines how different versions of the document
69 are to be created and which options of
70 .I nroff
71 or
72 .I troff
73 are appropriate.
74 .NH 2
75 Invocation and the argv variable
76 .PP
77 A
78 .I csh
79 command script may be interpreted by saying
80 .DS
81 % csh script ...
82 .DE
83 where
84 .I script
85 is the name of the file containing a group of
86 .I csh
87 commands and
88 `\&...' is replaced by a sequence of arguments.
89 The shell places these arguments in the variable
90 .I argv
91 and then begins to read commands from the script.
92 These parameters are then available through the same mechanisms
93 which are used to reference any other shell variables.
94 .PP
95 If you make the file
96 `script'
97 executable by doing
98 .DS
99 chmod 755 script
100 .DE
101 and place a shell comment at the beginning of the shell script
102 (i.e. begin the file with a `#' character)
103 then a `/bin/csh' will automatically be invoked to execute `script' when
104 you type
105 .DS
106 script
107 .DE
108 If the file does not begin with a `#' then the standard shell
109 `/bin/sh' will be used to execute it.
110 This allows you to convert your older shell scripts to use
111 .I csh
112 at your convenience.
113 .NH 2
114 Variable substitution
115 .PP
116 After each input line is broken into words and history substitutions
117 are done on it, the input line is parsed into distinct commands.
118 Before each command is executed a mechanism know as
119 .I "variable substitution"
120 is done on these words.
121 Keyed by the character `$' this substitution replaces the names
122 of variables by their values.
123 Thus
124 .DS
125 echo $argv
126 .DE
127 when placed in a command script would cause the current value of the
128 variable
129 .I argv
130 to be echoed to the output of the shell script.
131 It is an error for
132 .I argv
133 to be unset at this point.
134 .PP
135 A number of notations are provided for accessing components and attributes
136 of variables.
137 The notation
138 .DS
139 $?name
140 .DE
141 expands to `1' if name is
142 .I set
143 or to `0'
144 if name is not
145 .I set.
146 It is the fundamental mechanism used for checking whether particular
147 variables have been assigned values.
148 All other forms of reference to undefined variables cause errors.
149 .PP
150 The notation
151 .DS
152 $#name
153 .DE
154 expands to the number of elements in the variable
155 .I name.
156 Thus
157 .DS
158 % set argv=(a b c)
159 % echo $?argv
160 1
161 % echo $#argv
162 3
163 % unset argv
164 % echo $?argv
165 0
166 % echo $argv
167 Undefined variable: argv.
168 %
169 .DE
170 .PP
171 It is also possible to access the components of a variable
172 which has several values.
173 Thus
174 .DS
175 $argv[1]
176 .DE
177 gives the first component of
178 .I argv
179 or in the example above `a'.
180 Similarly
181 .DS
182 $argv[$#argv]
183 .DE
184 would give `c',
185 and
186 .DS
187 $argv[1\-2]
188 .DE
189 would give `a b'. Other notations useful in shell scripts are
190 .DS
191 $\fIn\fR
192 .DE
193 where
194 .I n
195 is an integer as a shorthand for
196 .DS
197 $argv[\fIn\fR\|]
198 .DE
199 the
200 .I n\|th
201 parameter and
202 .DS
203 $*
204 .DE
205 which is a shorthand for
206 .DS
207 $argv
208 .DE
209 The form
210 .DS
211 $$
212 .DE
213 expands to the process number of the current shell.
214 Since this process number is unique in the system it can
215 be used in generation of unique temporary file names.
216 The form
217 .DS
218 $<
219 .DE
220 is quite special and is replaced by the next line of input read from
221 the shell's standard input (not the script it is reading). This is
222 useful for writing shell scripts that are interactive, reading
223 commands from the terminal, or even writing a shell script that
224 acts as a filter, reading lines from its input file.
225 Thus the sequence
226 .DS
227 echo 'yes or no?\ec'
228 set a=($<)
229 .DE
230 would write out the prompt `yes or no?' without a newline and then
231 read the answer into the variable `a'. In this case `$#a' would be
232 `0' if either a blank line or end-of-file (^D) was typed.
233 .PP
234 One minor difference between `$\fIn\fR\|' and `$argv[\fIn\fR\|]'
235 should be noted here.
236 The form
237 `$argv[\fIn\fR\|]'
238 will yield an error if
239 .I n
240 is not in the range
241 `1\-$#argv'
242 while `$n'
243 will never yield an out of range subscript error.
244 This is for compatibility with the way older shells handled parameters.
245 .PP
246 Another important point is that it is never an error to give a subrange
247 of the form `n\-'; if there are less than
248 .I n
249 components of the given variable then no words are substituted.
250 A range of the form `m\-n' likewise returns an empty vector without giving
251 an error when \fIm\fR exceeds the number of elements of the given variable,
252 provided the subscript \fIn\fR is in range.
253 .NH 2
254 Expressions
255 .PP
256 In order for interesting shell scripts to be constructed it
257 must be possible to evaluate expressions in the shell based on the
258 values of variables.
259 In fact, all the arithmetic operations of the language C are available
260 in the shell
261 with the same precedence that they have in C.
262 In particular, the operations `==' and `!=' compare strings
263 and the operators `&&' and `|\|\||' implement the boolean and/or operations.
264 The special operators `=~' and `!~' are similar to `==' and `!=' except
265 that the string on the right side can have pattern matching characters
266 (like *, ? or []) and the test is whether the string on the left matches
267 the pattern on the right.
268 .PP
269 The shell also allows file enquiries of the form
270 .DS
271 \-? filename
272 .DE
273 where `?' is replace by a number of single characters.
274 For instance the expression primitive
275 .DS
276 \-e filename
277 .DE
278 tell whether the file
279 `filename'
280 exists.
281 Other primitives test for read, write and execute access to the file,
282 whether it is a directory, or has non-zero length.
283 .PP
284 It is possible to test whether a command terminates normally,
285 by a primitive of the
286 form `{ command }' which returns true, i.e. `1' if the command
287 succeeds exiting normally with exit status 0, or `0' if the command
288 terminates abnormally or with exit status non-zero.
289 If more detailed information about the execution status of a command
290 is required, it can be executed and the variable `$status' examined
291 in the next command.
292 Since `$status' is set by every command, it is very transient.
293 It can be saved if it is inconvenient to use it only in the single
294 immediately following command.
295 .PP
296 For a full list of expression components available see the manual
297 section for the shell.
298 .NH 2
299 Sample shell script
300 .PP
301 A sample shell script which makes use of the expression mechanism
302 of the shell and some of its control structure follows:
303 .DS
304 % cat copyc
305 #
306 # Copyc copies those C programs in the specified list
307 # to the directory ~/backup if they differ from the files
308 # already in ~/backup
309 #
310 set noglob
311 foreach i ($argv)
313 if ($i !~ *.c) continue # not a .c file so do nothing
315 if (! \-r ~/backup/$i:t) then
316 echo $i:t not in backup... not cp\e\'ed
317 continue
318 endif
320 cmp \-s $i ~/backup/$i:t # to set $status
322 if ($status != 0) then
323 echo new backup of $i
324 cp $i ~/backup/$i:t
325 endif
326 end
327 .DE
328 .PP
329 This script makes use of the
330 .I foreach
331 command, which causes the shell to execute the commands between the
332 .I foreach
333 and the matching
334 .I end
335 for each of the values given between `(' and `)' with the named
336 variable, in this case `i' set to successive values in the list.
337 Within this loop we may use the command
338 .I break
339 to stop executing the loop
340 and
341 .I continue
342 to prematurely terminate one iteration
343 and begin the next.
344 After the
345 .I foreach
346 loop the iteration variable
347 (\fIi\fR in this case)
348 has the value at the last iteration.
349 .PP
350 We set the variable
351 .I noglob
352 here to prevent filename expansion of the members of
353 .I argv.
354 This is a good idea, in general, if the arguments to a shell script
355 are filenames which have already been expanded or if the arguments
356 may contain filename expansion metacharacters.
357 It is also possible to quote each use of a `$' variable expansion,
358 but this is harder and less reliable.
359 .PP
360 The other control construct used here is a statement of the form
361 .DS
362 \fBif\fR ( expression ) \fBthen\fR
363 command
364 ...
365 \fBendif\fR
366 .DE
367 The placement of the keywords here is
368 .B not
369 flexible due to the current implementation of the shell.\(dg
370 .FS
371 \(dgThe following two formats are not currently acceptable to the shell:
372 .sp
373 .in +5
374 .nf
375 \fBif\fR ( expression ) # \fBWon't work!\fR
376 \fBthen\fR
377 command
378 ...
379 \fBendif\fR
380 .fi
381 .in -5
382 .sp
383 and
384 .sp
385 .in +5
386 .nf
387 \fBif\fR ( expression ) \fBthen\fR command \fBendif\fR # \fBWon't work\fR
388 .in -5
389 .fi
390 .FE
391 .PP
392 The shell does have another form of the if statement of the form
393 .DS
394 \fBif\fR ( expression ) \fBcommand\fR
395 .DE
396 which can be written
397 .DS
398 \fBif\fR ( expression ) \e
399 command
400 .DE
401 Here we have escaped the newline for the sake of appearance.
402 The command must not involve `\||\|', `&' or `;'
403 and must not be another control command.
404 The second form requires the final `\e' to
405 .B immediately
406 precede the end-of-line.
407 .PP
408 The more general
409 .I if
410 statements above also admit a sequence of
411 .I else\-if
412 pairs followed by a single
413 .I else
414 and an
415 .I endif,
416 e.g.:
417 .DS
418 \fBif\fR ( expression ) \fBthen\fR
419 commands
420 \fBelse\fR \fBif\fR (expression ) \fBthen\fR
421 commands
422 \&...
424 \fBelse\fR
425 commands
426 \fBendif\fR
427 .DE
428 .PP
429 Another important mechanism used in shell scripts is the `:' modifier.
430 We can use the modifier `:r' here to extract a root of a filename or
431 `:e' to extract the
432 .I extension.
433 Thus if the variable
434 .I i
435 has the value
436 `/mnt/foo.bar'
437 then
438 .sp
439 .in +5
440 .nf
441 % echo $i $i:r $i:e
442 /mnt/foo.bar /mnt/foo bar
443 %
444 .sp
445 .in -5
446 .fi
447 shows how the `:r' modifier strips off the trailing `.bar' and the
448 the `:e' modifier leaves only the `bar'.
449 Other modifiers will take off the last component of a pathname leaving
450 the head `:h' or all but the last component of a pathname leaving the
451 tail `:t'.
452 These modifiers are fully described in the
453 .I csh
454 manual pages in the User's Reference Manual.
455 It is also possible to use the
456 .I "command substitution"
457 mechanism described in the next major section to perform modifications
458 on strings to then reenter the shell's environment.
459 Since each usage of this mechanism involves the creation of a new process,
460 it is much more expensive to use than the `:' modification mechanism.\(dd
461 .FS
462 \(dd It is also important to note that
463 the current implementation of the shell limits the number of `:' modifiers
464 on a `$' substitution to 1.
465 Thus
466 .sp
467 .nf
468 .in +5
469 % echo $i $i:h:t
470 /a/b/c /a/b:t
471 %
472 .in -5
473 .fi
474 .sp
475 does not do what one would expect.
476 .FE
477 Finally, we note that the character `#' lexically introduces a shell
478 comment in shell scripts (but not from the terminal).
479 All subsequent characters on the input line after a `#' are discarded
480 by the shell.
481 This character can be quoted using `\'' or `\e' to place it in
482 an argument word.
483 .NH 2
484 Other control structures
485 .PP
486 The shell also has control structures
487 .I while
488 and
489 .I switch
490 similar to those of C.
491 These take the forms
492 .DS
493 \fBwhile\fR ( expression )
494 commands
495 \fBend\fR
496 .DE
497 and
498 .DS
499 \fBswitch\fR ( word )
501 \fBcase\fR str1:
502 commands
503 \fBbreaksw\fR
505 \& ...
507 \fBcase\fR strn:
508 commands
509 \fBbreaksw\fR
511 \fBdefault:\fR
512 commands
513 \fBbreaksw\fR
515 \fBendsw\fR
516 .DE
517 For details see the manual section for
518 .I csh.
519 C programmers should note that we use
520 .I breaksw
521 to exit from a
522 .I switch
523 while
524 .I break
525 exits a
526 .I while
527 or
528 .I foreach
529 loop.
530 A common mistake to make in
531 .I csh
532 scripts is to use
533 .I break
534 rather than
535 .I breaksw
536 in switches.
537 .PP
538 Finally,
539 .I csh
540 allows a
541 .I goto
542 statement, with labels looking like they do in C, i.e.:
543 .DS
544 loop:
545 commands
546 \fBgoto\fR loop
547 .DE
548 .NH 2
549 Supplying input to commands
550 .PP
551 Commands run from shell scripts receive by default the standard
552 input of the shell which is running the script.
553 This is different from previous shells running
554 under \s-2UNIX\s0. It allows shell scripts to fully participate
555 in pipelines, but mandates extra notation for commands which are to take
556 inline data.
557 .PP
558 Thus we need a metanotation for supplying inline data to commands in
559 shell scripts.
560 As an example, consider this script which runs the editor to
561 delete leading blanks from the lines in each argument file:
562 .DS
563 % cat deblank
564 # deblank \-\- remove leading blanks
565 foreach i ($argv)
566 ed \- $i << \'EOF\'
567 1,$s/^[ ]*//
568 w
569 q
570 \&\'EOF\'
571 end
572 %
573 .DE
574 The notation `<< \'EOF\''
575 means that the standard input for the
576 .I ed
577 command is to come from the text in the shell script file
578 up to the next line consisting of exactly `\'EOF\''.
579 The fact that the `EOF' is enclosed in `\'' characters, i.e. quoted,
580 causes the shell to not perform variable substitution on the
581 intervening lines.
582 In general, if any part of the word following the `<<' which the
583 shell uses to terminate the text to be given to the command is quoted
584 then these substitutions will not be performed.
585 In this case since we used the form `1,$' in our editor script
586 we needed to insure that this `$' was not variable substituted.
587 We could also have insured this by preceding the `$' here with a `\e',
588 i.e.:
589 .DS
590 1,\e$s/^[ ]*//
591 .DE
592 but quoting the `EOF' terminator is a more reliable way of achieving the
593 same thing.
594 .NH 2
595 Catching interrupts
596 .PP
597 If our shell script creates temporary files, we may wish to catch
598 interruptions of the shell script so that we can clean up
599 these files.
600 We can then do
601 .DS
602 onintr label
603 .DE
604 where
605 .I label
606 is a label in our program.
607 If an interrupt is received the shell will do a
608 `goto label'
609 and we can remove the temporary files and then do an
610 .I exit
611 command (which is built in to the shell)
612 to exit from the shell script.
613 If we wish to exit with a non-zero status we can do
614 .DS
615 exit(1)
616 .DE
617 e.g. to exit with status `1'.
618 .NH 2
619 What else?
620 .PP
621 There are other features of the shell useful to writers of shell
622 procedures.
623 The
624 .I verbose
625 and
626 .I echo
627 options and the related
628 .I \-v
629 and
630 .I \-x
631 command line options can be used to help trace the actions of the shell.
632 The
633 .I \-n
634 option causes the shell only to read commands and not to execute
635 them and may sometimes be of use.
636 .PP
637 One other thing to note is that
638 .I csh
639 will not execute shell scripts which do not begin with the
640 character `#', that is shell scripts that do not begin with a comment.
641 Similarly, the `/bin/sh' on your system may well defer to `csh'
642 to interpret shell scripts which begin with `#'.
643 This allows shell scripts for both shells to live in harmony.
644 .PP
645 There is also another quotation mechanism using `"' which allows
646 only some of the expansion mechanisms we have so far discussed to occur
647 on the quoted string and serves to make this string into a single word
648 as `\'' does.
649 .bp