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