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