| blob | a6a6f66e865c8395fd1187ed419407828e3fd6af |
1 .\" $NetBSD: csh.3,v 1.5 2003/08/07 09:05:08 agc Exp $
2 .\"
3 .\" Copyright (c) 1980, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)csh.3 8.1 (Berkeley) 6/8/93
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. Thus the sequence
225 .DS
226 echo 'yes or no?\ec'
227 set a=($<)
228 .DE
229 would write out the prompt `yes or no?' without a newline and then
230 read the answer into the variable `a'. In this case `$#a' would be
231 `0' if either a blank line or end-of-file (^D) was typed.
232 .PP
233 One minor difference between `$\fIn\fR\|' and `$argv[\fIn\fR\|]'
234 should be noted here.
235 The form
236 `$argv[\fIn\fR\|]'
237 will yield an error if
238 .I n
239 is not in the range
240 `1\-$#argv'
241 while `$n'
242 will never yield an out of range subscript error.
243 This is for compatibility with the way older shells handled parameters.
244 .PP
245 Another important point is that it is never an error to give a subrange
246 of the form `n\-'; if there are less than
247 .I n
248 components of the given variable then no words are substituted.
249 A range of the form `m\-n' likewise returns an empty vector without giving
250 an error when \fIm\fR exceeds the number of elements of the given variable,
251 provided the subscript \fIn\fR is in range.
252 .NH 2
253 Expressions
254 .PP
255 In order for interesting shell scripts to be constructed it
256 must be possible to evaluate expressions in the shell based on the
257 values of variables.
258 In fact, all the arithmetic operations of the language C are available
259 in the shell
260 with the same precedence that they have in C.
261 In particular, the operations `==' and `!=' compare strings
262 and the operators `&&' and `|\|\||' implement the boolean and/or operations.
263 The special operators `=~' and `!~' are similar to `==' and `!=' except
264 that the string on the right side can have pattern matching characters
265 (like *, ? or []) and the test is whether the string on the left matches
266 the pattern on the right.
267 .PP
268 The shell also allows file enquiries of the form
269 .DS
270 \-? filename
271 .DE
272 where `?' is replace by a number of single characters.
273 For instance the expression primitive
274 .DS
275 \-e filename
276 .DE
277 tell whether the file
278 `filename'
279 exists.
280 Other primitives test for read, write and execute access to the file,
281 whether it is a directory, or has non-zero length.
282 .PP
283 It is possible to test whether a command terminates normally,
284 by a primitive of the
285 form `{ command }' which returns true, i.e. `1' if the command
286 succeeds exiting normally with exit status 0, or `0' if the command
287 terminates abnormally or with exit status non-zero.
288 If more detailed information about the execution status of a command
289 is required, it can be executed and the variable `$status' examined
290 in the next command.
291 Since `$status' is set by every command, it is very transient.
292 It can be saved if it is inconvenient to use it only in the single
293 immediately following command.
294 .PP
295 For a full list of expression components available see the manual
296 section for the shell.
297 .NH 2
298 Sample shell script
299 .PP
300 A sample shell script which makes use of the expression mechanism
301 of the shell and some of its control structure follows:
302 .DS
303 % cat copyc
304 #
305 # Copyc copies those C programs in the specified list
306 # to the directory ~/backup if they differ from the files
307 # already in ~/backup
308 #
309 set noglob
310 foreach i ($argv)
312 if ($i !~ *.c) continue # not a .c file so do nothing
314 if (! \-r ~/backup/$i:t) then
315 echo $i:t not in backup... not cp\e\'ed
316 continue
317 endif
319 cmp \-s $i ~/backup/$i:t # to set $status
321 if ($status != 0) then
322 echo new backup of $i
323 cp $i ~/backup/$i:t
324 endif
325 end
326 .DE
327 .PP
328 This script makes use of the
329 .I foreach
330 command, which causes the shell to execute the commands between the
331 .I foreach
332 and the matching
333 .I end
334 for each of the values given between `(' and `)' with the named
335 variable, in this case `i' set to successive values in the list.
336 Within this loop we may use the command
337 .I break
338 to stop executing the loop
339 and
340 .I continue
341 to prematurely terminate one iteration
342 and begin the next.
343 After the
344 .I foreach
345 loop the iteration variable
346 (\fIi\fR in this case)
347 has the value at the last iteration.
348 .PP
349 We set the variable
350 .I noglob
351 here to prevent filename expansion of the members of
352 .I argv.
353 This is a good idea, in general, if the arguments to a shell script
354 are filenames which have already been expanded or if the arguments
355 may contain filename expansion metacharacters.
356 It is also possible to quote each use of a `$' variable expansion,
357 but this is harder and less reliable.
358 .PP
359 The other control construct used here is a statement of the form
360 .DS
361 \fBif\fR ( expression ) \fBthen\fR
362 command
363 ...
364 \fBendif\fR
365 .DE
366 The placement of the keywords here is
367 .B not
368 flexible due to the current implementation of the shell.\(dg
369 .FS
370 \(dgThe following two formats are not currently acceptable to the shell:
371 .sp
372 .in +5
373 .nf
374 \fBif\fR ( expression ) # \fBWon't work!\fR
375 \fBthen\fR
376 command
377 ...
378 \fBendif\fR
379 .fi
380 .in -5
381 .sp
382 and
383 .sp
384 .in +5
385 .nf
386 \fBif\fR ( expression ) \fBthen\fR command \fBendif\fR # \fBWon't work\fR
387 .in -5
388 .fi
389 .FE
390 .PP
391 The shell does have another form of the if statement of the form
392 .DS
393 \fBif\fR ( expression ) \fBcommand\fR
394 .DE
395 which can be written
396 .DS
397 \fBif\fR ( expression ) \e
398 command
399 .DE
400 Here we have escaped the newline for the sake of appearance.
401 The command must not involve `\||\|', `&' or `;'
402 and must not be another control command.
403 The second form requires the final `\e' to
404 .B immediately
405 precede the end-of-line.
406 .PP
407 The more general
408 .I if
409 statements above also admit a sequence of
410 .I else\-if
411 pairs followed by a single
412 .I else
413 and an
414 .I endif,
415 e.g.:
416 .DS
417 \fBif\fR ( expression ) \fBthen\fR
418 commands
419 \fBelse\fR \fBif\fR (expression ) \fBthen\fR
420 commands
421 \&...
423 \fBelse\fR
424 commands
425 \fBendif\fR
426 .DE
427 .PP
428 Another important mechanism used in shell scripts is the `:' modifier.
429 We can use the modifier `:r' here to extract a root of a filename or
430 `:e' to extract the
431 .I extension.
432 Thus if the variable
433 .I i
434 has the value
435 `/mnt/foo.bar'
436 then
437 .sp
438 .in +5
439 .nf
440 % echo $i $i:r $i:e
441 /mnt/foo.bar /mnt/foo bar
442 %
443 .sp
444 .in -5
445 .fi
446 shows how the `:r' modifier strips off the trailing `.bar' and the
447 the `:e' modifier leaves only the `bar'.
448 Other modifiers will take off the last component of a pathname leaving
449 the head `:h' or all but the last component of a pathname leaving the
450 tail `:t'.
451 These modifiers are fully described in the
452 .I csh
453 manual pages in the User's Reference Manual.
454 It is also possible to use the
455 .I "command substitution"
456 mechanism described in the next major section to perform modifications
457 on strings to then reenter the shell's environment.
458 Since each usage of this mechanism involves the creation of a new process,
459 it is much more expensive to use than the `:' modification mechanism.\(dd
460 .FS
461 \(dd It is also important to note that
462 the current implementation of the shell limits the number of `:' modifiers
463 on a `$' substitution to 1.
464 Thus
465 .sp
466 .nf
467 .in +5
468 % echo $i $i:h:t
469 /a/b/c /a/b:t
470 %
471 .in -5
472 .fi
473 .sp
474 does not do what one would expect.
475 .FE
476 Finally, we note that the character `#' lexically introduces a shell
477 comment in shell scripts (but not from the terminal).
478 All subsequent characters on the input line after a `#' are discarded
479 by the shell.
480 This character can be quoted using `\'' or `\e' to place it in
481 an argument word.
482 .NH 2
483 Other control structures
484 .PP
485 The shell also has control structures
486 .I while
487 and
488 .I switch
489 similar to those of C.
490 These take the forms
491 .DS
492 \fBwhile\fR ( expression )
493 commands
494 \fBend\fR
495 .DE
496 and
497 .DS
498 \fBswitch\fR ( word )
500 \fBcase\fR str1:
501 commands
502 \fBbreaksw\fR
504 \& ...
506 \fBcase\fR strn:
507 commands
508 \fBbreaksw\fR
510 \fBdefault:\fR
511 commands
512 \fBbreaksw\fR
514 \fBendsw\fR
515 .DE
516 For details see the manual section for
517 .I csh.
518 C programmers should note that we use
519 .I breaksw
520 to exit from a
521 .I switch
522 while
523 .I break
524 exits a
525 .I while
526 or
527 .I foreach
528 loop.
529 A common mistake to make in
530 .I csh
531 scripts is to use
532 .I break
533 rather than
534 .I breaksw
535 in switches.
536 .PP
537 Finally,
538 .I csh
539 allows a
540 .I goto
541 statement, with labels looking like they do in C, i.e.:
542 .DS
543 loop:
544 commands
545 \fBgoto\fR loop
546 .DE
547 .NH 2
548 Supplying input to commands
549 .PP
550 Commands run from shell scripts receive by default the standard
551 input of the shell which is running the script.
552 This is different from previous shells running
553 under \s-2UNIX\s0. It allows shell scripts to fully participate
554 in pipelines, but mandates extra notation for commands which are to take
555 inline data.
556 .PP
557 Thus we need a metanotation for supplying inline data to commands in
558 shell scripts.
559 As an example, consider this script which runs the editor to
560 delete leading blanks from the lines in each argument file:
561 .DS
562 % cat deblank
563 # deblank \-\- remove leading blanks
564 foreach i ($argv)
565 ed \- $i << \'EOF\'
566 1,$s/^[ ]*//
567 w
568 q
569 \&\'EOF\'
570 end
571 %
572 .DE
573 The notation `<< \'EOF\''
574 means that the standard input for the
575 .I ed
576 command is to come from the text in the shell script file
577 up to the next line consisting of exactly `\'EOF\''.
578 The fact that the `EOF' is enclosed in `\'' characters, i.e. quoted,
579 causes the shell to not perform variable substitution on the
580 intervening lines.
581 In general, if any part of the word following the `<<' which the
582 shell uses to terminate the text to be given to the command is quoted
583 then these substitutions will not be performed.
584 In this case since we used the form `1,$' in our editor script
585 we needed to insure that this `$' was not variable substituted.
586 We could also have insured this by preceding the `$' here with a `\e',
587 i.e.:
588 .DS
589 1,\e$s/^[ ]*//
590 .DE
591 but quoting the `EOF' terminator is a more reliable way of achieving the
592 same thing.
593 .NH 2
594 Catching interrupts
595 .PP
596 If our shell script creates temporary files, we may wish to catch
597 interruptions of the shell script so that we can clean up
598 these files.
599 We can then do
600 .DS
601 onintr label
602 .DE
603 where
604 .I label
605 is a label in our program.
606 If an interrupt is received the shell will do a
607 `goto label'
608 and we can remove the temporary files and then do an
609 .I exit
610 command (which is built in to the shell)
611 to exit from the shell script.
612 If we wish to exit with a non-zero status we can do
613 .DS
614 exit(1)
615 .DE
616 e.g. to exit with status `1'.
617 .NH 2
618 What else?
619 .PP
620 There are other features of the shell useful to writers of shell
621 procedures.
622 The
623 .I verbose
624 and
625 .I echo
626 options and the related
627 .I \-v
628 and
629 .I \-x
630 command line options can be used to help trace the actions of the shell.
631 The
632 .I \-n
633 option causes the shell only to read commands and not to execute
634 them and may sometimes be of use.
635 .PP
636 One other thing to note is that
637 .I csh
638 will not execute shell scripts which do not begin with the
639 character `#', that is shell scripts that do not begin with a comment.
640 Similarly, the `/bin/sh' on your system may well defer to `csh'
641 to interpret shell scripts which begin with `#'.
642 This allows shell scripts for both shells to live in harmony.
643 .PP
644 There is also another quotation mechanism using `"' which allows
645 only some of the expansion mechanisms we have so far discussed to occur
646 on the quoted string and serves to make this string into a single word
647 as `\'' does.
648 .bp