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