1CSH(1)                      General Commands Manual                     CSH(1)
2
3
4

NAME

6       csh - a shell (command interpreter) with C-like syntax
7

SYNOPSIS

9       csh [ -cefinstvVxX ] [ arg ...  ]
10

DESCRIPTION

12       Csh  is a first implementation of a command language interpreter incor‐
13       porating a history mechanism (see History Substitutions),  job  control
14       facilities  (see  Jobs), interactive file name and user name completion
15       (see File Name Completion), and a C-like syntax.  So as to be  able  to
16       use  its  job control facilities, users of csh must (and automatically)
17       use the new tty driver fully described in tty(4).  This new tty  driver
18       allows  generation  of  interrupt  characters from the keyboard to tell
19       jobs to stop.  See stty(1) for details on setting options  in  the  new
20       tty driver.
21
22       An  instance of csh begins by executing commands from the file `.cshrc'
23       in the home directory of the invoker.  If this is a login shell then it
24       also executes commands from the file `.login' there.  It is typical for
25       users on crt's to put the command ``stty crt'' in  their  .login  file,
26       and to also invoke tset(1) there.
27
28       In the normal case, the shell will then begin reading commands from the
29       terminal, prompting with `% '.  Processing of arguments and the use  of
30       the shell to process files containing command scripts will be described
31       later.
32
33       The shell then repeatedly performs the following  actions:  a  line  of
34       command input is read and broken into words.  This sequence of words is
35       placed on the command history list and then parsed.  Finally each  com‐
36       mand in the current line is executed.
37
38       When  a  login  shell  terminates  it  executes  commands from the file
39       `.logout' in the users home directory.
40
41       Lexical structure
42
43       The shell splits input lines into words at blanks  and  tabs  with  the
44       following  exceptions.  The characters `&' `|' `;' `<' `>' `(' `)' form
45       separate words.  If doubled in `&&', `||', `<<'  or  `>>'  these  pairs
46       form  single  words.   These  parser metacharacters may be made part of
47       other words, or prevented their special meaning, by preceding them with
48       `\'.  A newline preceded by a `\' is equivalent to a blank.
49
50       In  addition  strings enclosed in matched pairs of quotations, `'', ``'
51       or `"', form parts of a word; metacharacters in these strings,  includ‐
52       ing blanks and tabs, do not form separate words.  These quotations have
53       semantics to be described subsequently.  Within pairs  of  `´'  or  `"'
54       characters a newline preceded by a `\' gives a true newline character.
55
56       When  the shell's input is not a terminal, the character `#' introduces
57       a comment which continues to the end of the input  line.   It  is  pre‐
58       vented  this  special  meaning  when  preceded by `\' and in quotations
59       using ``', `´', and `"'.
60
61       Commands
62
63       A simple command is a sequence of words, the first of  which  specifies
64       the  command  to be executed.  A simple command or a sequence of simple
65       commands separated by `|' characters forms a pipeline.  The  output  of
66       each  command  in  a  pipeline  is  connected to the input of the next.
67       Sequences of pipelines may be separated by `;', and are  then  executed
68       sequentially.   A sequence of pipelines may be executed without immedi‐
69       ately waiting for it to terminate by following it with an `&'.
70
71       Any of the above may be placed in `(' `)'  to  form  a  simple  command
72       (which  may be a component of a pipeline, etc.)  It is also possible to
73       separate pipelines with `||' or `&&' indicating, as in the C  language,
74       that  the  second is to be executed only if the first fails or succeeds
75       respectively. (See Expressions.)
76
77       Jobs
78
79       The shell associates a job with each pipeline.  It  keeps  a  table  of
80       current jobs, printed by the jobs command, and assigns them small inte‐
81       ger numbers.  When a job is started asynchronously with `&', the  shell
82       prints a line which looks like:
83
84            [1] 1234
85
86       indicating that the job which was started asynchronously was job number
87       1 and had one (top-level) process, whose process id was 1234.
88
89       If you are running a job and wish to do something else you may hit  the
90       key  ^Z  (control-Z) which sends a STOP signal to the current job.  The
91       shell will then normally indicate that the job has been `Stopped',  and
92       print  another  prompt.  You can then manipulate the state of this job,
93       putting it in the background with the bg command,  or  run  some  other
94       commands  and  then  eventually  bring the job back into the foreground
95       with the foreground command fg.  A ^Z takes effect immediately  and  is
96       like an interrupt in that pending output and unread input are discarded
97       when it is typed.  There is another special key ^Y which does not  gen‐
98       erate  a  STOP signal until a program attempts to read(2) it.  This can
99       usefully be typed ahead when you have prepared some commands for a  job
100       which you wish to stop after it has read them.
101
102       A  job  being  run in the background will stop if it tries to read from
103       the terminal.  Background jobs are normally allowed to produce  output,
104       but this can be disabled by giving the command ``stty tostop''.  If you
105       set this tty option, then background jobs will stop when  they  try  to
106       produce output like they do when they try to read input.
107
108       There  are  several  ways to refer to jobs in the shell.  The character
109       `%' introduces a job name.  If you wish to refer to job number  1,  you
110       can  name  it  as `%1'.  Just naming a job brings it to the foreground;
111       thus `%1' is a synonym for `fg %1', bringing job 1 back into the  fore‐
112       ground.  Similarly saying `%1 &' resumes job 1 in the background.  Jobs
113       can also be named by prefixes of the string typed in to start them,  if
114       these  prefixes  are  unambiguous,  thus `%ex' would normally restart a
115       suspended ex(1) job, if there were only one suspended  job  whose  name
116       began  with  the  string  `ex'.   It is also possible to say `%?string'
117       which specifies a job whose text contains string, if there is only  one
118       such job.
119
120       The shell maintains a notion of the current and previous jobs.  In out‐
121       put pertaining to jobs, the current job is marked with a  `+'  and  the
122       previous  job  with a `-'.  The abbreviation `%+' refers to the current
123       job and `%-' refers to the previous job.  For close  analogy  with  the
124       syntax  of the history mechanism (described below), `%%' is also a syn‐
125       onym for the current job.
126
127       Status reporting
128
129       This shell learns immediately whenever a  process  changes  state.   It
130       normally  informs you whenever a job becomes blocked so that no further
131       progress is possible, but only just before it prints a prompt.  This is
132       done so that it does not otherwise disturb your work.  If, however, you
133       set the shell variable notify, the shell will notify you immediately of
134       changes  of  status  in background jobs.  There is also a shell command
135       notify which marks a single process so that its status changes will  be
136       immediately  reported.   By  default  notify marks the current process;
137       simply say `notify' after starting a background job to mark it.
138
139       When you try to leave the shell while jobs are  stopped,  you  will  be
140       warned  that  `You have stopped jobs.'  You may use the jobs command to
141       see what they are.  If you do this or immediately try  to  exit  again,
142       the  shell will not warn you a second time, and the suspended jobs will
143       be terminated.
144
145       File Name Completion
146
147       When the file name completion feature is enabled by setting  the  shell
148       variable  filec  (see  set), csh will interactively complete file names
149       and user names from unique prefixes, when they are input from the  ter‐
150       minal  followed by the escape character (the escape key, or control-[).
151       For example, if the current directory looks like
152                 DSC.OLD   bin       cmd       lib       xmpl.c
153                 DSC.NEW   chaosnet  cmtest    mail      xmpl.o
154                 bench     class     dev       mbox      xmpl.out
155       and the input is
156                 % vi ch<escape>
157       csh will complete the prefix ``ch'' to  the  only  matching  file  name
158       ``chaosnet'', changing the input line to
159                 % vi chaosnet
160       However, given
161                 % vi D<escape>
162       csh will only expand the input to
163                 % vi DSC.
164       and  will  sound  the  terminal  bell to indicate that the expansion is
165       incomplete, since there are two file names matching the prefix ``D''.
166
167       If a partial file name is followed by the end-of-file  character  (usu‐
168       ally  control-D),  then,  instead of completing the name, csh will list
169       all file names matching the prefix.  For example, the input
170                 % vi D<control-D>
171       causes all files beginning with ``D'' to be listed:
172                 DSC.NEW   DSC.OLD
173       while the input line remains unchanged.
174
175       The same system of escape and end-of-file can also be  used  to  expand
176       partial user names, if the word to be completed (or listed) begins with
177       the character ``~''.  For example, typing
178                 cd ~ro<control-D>
179       may produce the expansion
180                 cd ~root
181
182       The use of the terminal bell to signal errors or multiple  matches  can
183       be inhibited by setting the variable nobeep.
184
185       Normally, all files in the particular directory are candidates for name
186       completion.  Files with certain suffixes can be excluded from consider‐
187       ation  by  setting  the  variable fignore to the list of suffixes to be
188       ignored.  Thus, if fignore is set by the command
189                 % set fignore = (.o .out)
190       then typing
191                 % vi x<escape>
192       would result in the completion to
193                 % vi xmpl.c
194       ignoring the files "xmpl.o" and "xmpl.out".  However, if the only  com‐
195       pletion  possible  requires  not ignoring these suffixes, then they are
196       not ignored.  In addition, fignore does not affect the listing of  file
197       names by control-D.  All files are listed regardless of their suffixes.
198
199       Substitutions
200
201       We  now  describe the various transformations the shell performs on the
202       input in the order in which they occur.
203
204       History substitutions
205
206       History substitutions place words from previous command input  as  por‐
207       tions  of new commands, making it easy to repeat commands, repeat argu‐
208       ments of a previous command in the current  command,  or  fix  spelling
209       mistakes  in  the previous command with little typing and a high degree
210       of confidence.  History substitutions begin with the character `!'  and
211       may  begin  anywhere in the input stream (with the proviso that they do
212       not nest.)  This `!' may be preceded by an `\' to prevent  its  special
213       meaning; for convenience, a `!' is passed unchanged when it is followed
214       by a blank, tab, newline, `='  or  `('.   (History  substitutions  also
215       occur  when  an  input line begins with `^'.  This special abbreviation
216       will be described later.)  Any input line which contains  history  sub‐
217       stitution  is  echoed on the terminal before it is executed as it could
218       have been typed without history substitution.
219
220       Commands input from the terminal which consist of one or more words are
221       saved  on  the  history  list.   The  history substitutions reintroduce
222       sequences of words from these saved commands  into  the  input  stream.
223       The  size  of which is controlled by the history variable; the previous
224       command is always retained, regardless of its value.  Commands are num‐
225       bered sequentially from 1.
226
227       For  definiteness,  consider the following output from the history com‐
228       mand:
229
230             9  write michael
231            10  ex write.c
232            11  cat oldwrite.c
233            12  diff *write.c
234
235       The commands are shown with their event numbers.   It  is  not  usually
236       necessary  to  use  event  numbers, but the current event number can be
237       made part of the prompt by placing an `!' in the prompt string.
238
239       With the current event 13 we can refer to previous events by event num‐
240       ber  `!11',  relatively as in `!-2' (referring to the same event), by a
241       prefix of a command word as in `!d' for event 12 or `!wri' for event 9,
242       or  by  a string contained in a word in the command as in `!?mic?' also
243       referring to event 9.  These forms, without further modification,  sim‐
244       ply  reintroduce the words of the specified events, each separated by a
245       single blank.  As a special case `!!' refers to the  previous  command;
246       thus `!!'  alone is essentially a redo.
247
248       To  select words from an event we can follow the event specification by
249       a `:' and a designator for the desired words.  The words  of  an  input
250       line are numbered from 0, the first (usually command) word being 0, the
251       second word (first argument) being 1, etc.  The basic word  designators
252       are:
253
254            0    first (command) word
255            n    n'th argument
256            ^    first argument,  i.e. `1'
257            $    last argument
258            %    word matched by (immediately preceding) ?s? search
259            x-y  range of words
260            -y   abbreviates `0-y'
261            *    abbreviates `^-$', or nothing if only 1 word in event
262            x*   abbreviates `x-$'
263            x-   like `x*' but omitting word `$'
264
265       The `:' separating the event specification from the word designator can
266       be omitted if the argument selector begins with a `^', `$', `*' `-'  or
267       `%'.   After  the  optional word designator can be placed a sequence of
268       modifiers, each  preceded  by  a  `:'.   The  following  modifiers  are
269       defined:
270
271            h      Remove a trailing pathname component, leaving the head.
272            r      Remove a trailing `.xxx' component, leaving the root name.
273            e      Remove all but the extension `.xxx' part.
274            s/l/r/ Substitute l for r
275            t      Remove all leading pathname components, leaving the tail.
276            &      Repeat the previous substitution.
277            g      Apply the change globally, prefixing the above, e.g. `g&'.
278            p      Print the new command but do not execute it.
279            q      Quote the substituted words, preventing further substitutions.
280            x      Like q, but break into words at blanks, tabs and newlines.
281
282       Unless  preceded by a `g' the modification is applied only to the first
283       modifiable word.  With substitutions, it is an error for no word to  be
284       applicable.
285
286       The  left hand side of substitutions are not regular expressions in the
287       sense of the editors, but rather strings.  Any character may be used as
288       the  delimiter  in  place of `/'; a `\' quotes the delimiter into the l
289       and r strings.  The character `&' in the right hand side is replaced by
290       the text from the left.  A `\' quotes `&' also.  A null l uses the pre‐
291       vious string either from a l or from a  contextual  scan  string  s  in
292       `!?s?'.  The trailing delimiter in the substitution may be omitted if a
293       newline follows immediately as may the trailing  `?'  in  a  contextual
294       scan.
295
296       A  history  reference may be given without an event specification, e.g.
297       `!$'.  In this case the reference is to the previous command  unless  a
298       previous history reference occurred on the same line in which case this
299       form repeats the previous reference.  Thus `!?foo?^ !$' gives the first
300       and last arguments from the command matching `?foo?'.
301
302       A  special  abbreviation  of  a history reference occurs when the first
303       non-blank character of an input line is a `^'.  This is  equivalent  to
304       `!:s^'  providing  a convenient shorthand for substitutions on the text
305       of the previous line.  Thus `^lb^lib' fixes the spelling  of  `lib'  in
306       the  previous  command.   Finally,  a  history substitution may be sur‐
307       rounded with `{' and `}' if necessary to insulate it from  the  charac‐
308       ters  which  follow.  Thus, after `ls -ld ~paul' we might do `!{l}a' to
309       do `ls -ld ~paula', while `!la' would look for a command starting `la'.
310
311       Quotations with ´ and "
312
313       The quotation of strings by `´' and `"' can be used to prevent  all  or
314       some  of the remaining substitutions.  Strings enclosed in `´' are pre‐
315       vented any further interpretation.  Strings  enclosed  in  `"'  may  be
316       expanded as described below.
317
318       In  both  cases  the  resulting  text becomes (all or part of) a single
319       word; only in one special case (see Command Substitition below) does  a
320       `"' quoted string yield parts of more than one word; `´' quoted strings
321       never do.
322
323       Alias substitution
324
325       The shell maintains a list of aliases which can  be  established,  dis‐
326       played and modified by the alias and unalias commands.  After a command
327       line is scanned, it is parsed into distinct commands and the first word
328       of  each  command, left-to-right, is checked to see if it has an alias.
329       If it does, then the text which is the alias for that command is reread
330       with  the  history  mechanism available as though that command were the
331       previous input line.  The resulting words replace the command and argu‐
332       ment list.  If no reference is made to the history list, then the argu‐
333       ment list is left unchanged.
334
335       Thus if the alias for `ls' is `ls -l' the command `ls /usr'  would  map
336       to  `ls  -l /usr', the argument list here being undisturbed.  Similarly
337       if the alias for `lookup' was `grep !^ /etc/passwd' then `lookup  bill'
338       would map to `grep bill /etc/passwd'.
339
340       If an alias is found, the word transformation of the input text is per‐
341       formed and the aliasing process begins  again  on  the  reformed  input
342       line.   Looping  is  prevented if the first word of the new text is the
343       same as the old by flagging it  to  prevent  further  aliasing.   Other
344       loops are detected and cause an error.
345
346       Note  that the mechanism allows aliases to introduce parser metasyntax.
347       Thus we can `alias print ´pr \!* | lpr´' to make a command  which  pr's
348       its arguments to the line printer.
349
350       Variable substitution
351
352       The  shell  maintains  a set of variables, each of which has as value a
353       list of zero or more words.  Some of these variables  are  set  by  the
354       shell  or  referred  to  by  it.  For instance, the argv variable is an
355       image of the shell's argument list, and words of this variable's  value
356       are referred to in special ways.
357
358       The  values  of variables may be displayed and changed by using the set
359       and unset commands.  Of the variables referred to by the shell a number
360       are  toggles; the shell does not care what their value is, only whether
361       they are set or not.  For instance, the verbose variable  is  a  toggle
362       which  causes command input to be echoed.  The setting of this variable
363       results from the -v command line option.
364
365       Other operations treat variables numerically.  The `@' command  permits
366       numeric calculations to be performed and the result assigned to a vari‐
367       able.  Variable values are, however, always  represented  as  (zero  or
368       more) strings.  For the purposes of numeric operations, the null string
369       is considered to be zero, and the second and subsequent words of multi‐
370       word values are ignored.
371
372       After  the input line is aliased and parsed, and before each command is
373       executed, variable substitution is performed keyed by  `$'  characters.
374       This  expansion can be prevented by preceding the `$' with a `\' except
375       within `"'s where it always occurs, and  within  `´'s  where  it  never
376       occurs.   Strings quoted by ``' are interpreted later (see Command sub‐
377       stitution below) so `$' substitution does not occur there until  later,
378       if  at  all.  A `$' is passed unchanged if followed by a blank, tab, or
379       end-of-line.
380
381       Input/output redirections are recognized before variable expansion, and
382       are  variable  expanded  separately.   Otherwise,  the command name and
383       entire argument list are expanded together.  It is  thus  possible  for
384       the  first (command) word to this point to generate more than one word,
385       the first of which becomes the command name,  and  the  rest  of  which
386       become arguments.
387
388       Unless  enclosed in `"' or given the `:q' modifier the results of vari‐
389       able substitution may eventually be command and  filename  substituted.
390       Within  `"',  a variable whose value consists of multiple words expands
391       to a (portion of) a single word, with the words of the variables  value
392       separated  by blanks.  When the `:q' modifier is applied to a substitu‐
393       tion the variable will expand to multiple words with  each  word  sepa‐
394       rated  by  a blank and quoted to prevent later command or filename sub‐
395       stitution.
396
397       The following metasequences are provided for introducing variable  val‐
398       ues into the shell input.  Except as noted, it is an error to reference
399       a variable which is not set.
400
401       $name
402       ${name}
403            Are replaced by the words of the value of variable name, each sep‐
404            arated by a blank.  Braces insulate name from following characters
405            which would otherwise be part of it.  Shell variables  have  names
406            consisting  of up to 20 letters and digits starting with a letter.
407            The underscore character is considered a letter.
408            If name is not a shell variable, but is set  in  the  environment,
409            then  that  value is returned (but : modifiers and the other forms
410            given below are not available in this case).
411
412       $name[selector]
413       ${name[selector]}
414            May be used to select only some of the words  from  the  value  of
415            name.   The selector is subjected to `$' substitution and may con‐
416            sist of a single number or two numbers separated by  a  `-'.   The
417            first  word  of  a  variables value is numbered `1'.  If the first
418            number of a range is omitted it defaults to `1'.  If the last mem‐
419            ber  of  a range is omitted it defaults to `$#name'.  The selector
420            `*' selects all words.  It is not an error for a range to be empty
421            if the second argument is omitted or in range.
422
423       $#name
424       ${#name}
425            Gives  the  number  of  words in the variable.  This is useful for
426            later use in a `[selector]'.
427
428       $0
429            Substitutes the name of the file from which command input is being
430            read.  An error occurs if the name is not known.
431
432       $number
433       ${number}
434            Equivalent to `$argv[number]'.
435
436       $*
437            Equivalent to `$argv[*]'.
438
439       The  modifiers  `:h',  `:t',  `:r', `:q' and `:x' may be applied to the
440       substitutions above as may `:gh', `:gt' and `:gr'.  If braces  `{'  '}'
441       appear  in  the  command form then the modifiers must appear within the
442       braces.  The current implementation allows only  one  `:'  modifier  on
443       each `$' expansion.
444
445       The following substitutions may not be modified with `:' modifiers.
446
447       $?name
448       ${?name}
449            Substitutes the string `1' if name is set, `0' if it is not.
450
451       $?0
452            Substitutes  `1' if the current input filename is known, `0' if it
453            is not.
454
455       $$
456            Substitute the (decimal) process number of the (parent) shell.
457
458       $<
459            Substitutes a line from the standard input, with no further inter‐
460            pretation thereafter.  It can be used to read from the keyboard in
461            a shell script.
462
463       Command and filename substitution
464
465       The remaining substitutions, command  and  filename  substitution,  are
466       applied  selectively  to the arguments of builtin commands.  This means
467       that portions of expressions which are not evaluated are not  subjected
468       to these expansions.  For commands which are not internal to the shell,
469       the command name is substituted  separately  from  the  argument  list.
470       This occurs very late, after input-output redirection is performed, and
471       in a child of the main shell.
472
473       Command substitution
474
475       Command substitution is indicated by a command enclosed  in  ``'.   The
476       output  from  such  a command is normally broken into separate words at
477       blanks, tabs and newlines, with null words being discarded,  this  text
478       then  replacing  the original string.  Within `"'s, only newlines force
479       new words; blanks and tabs are preserved.
480
481       In any case, the single final newline does not force a new word.   Note
482       that  it is thus possible for a command substitution to yield only part
483       of a word, even if the command outputs a complete line.
484
485       Filename substitution
486
487       If a word contains any of the characters `*', `?', `[' or `{' or begins
488       with the character `~', then that word is a candidate for filename sub‐
489       stitution, also known as `globbing'.  This word is then regarded  as  a
490       pattern,  and replaced with an alphabetically sorted list of file names
491       which match the pattern.  In a list of words specifying  filename  sub‐
492       stitution it is an error for no pattern to match an existing file name,
493       but it is not required for each pattern to match.  Only the metacharac‐
494       ters  `*',  `?'  and `[' imply pattern matching, the characters `~' and
495       `{' being more akin to abbreviations.
496
497       In matching filenames, the character `.' at the beginning of a filename
498       or  immediately  following  a `/', as well as the character `/' must be
499       matched explicitly.  The character `*' matches any  string  of  charac‐
500       ters,  including the null string.  The character `?' matches any single
501       character.  The sequence `[...]' matches  any  one  of  the  characters
502       enclosed.   Within  `[...]',  a  pair  of  characters  separated by `-'
503       matches any character lexically between the two.
504
505       The character `~' at the beginning of a filename is used  to  refer  to
506       home  directories.  Standing alone, i.e. `~' it expands to the invokers
507       home directory as reflected in the value of the  variable  home.   When
508       followed by a name consisting of letters, digits and `-' characters the
509       shell searches for a user with that name  and  substitutes  their  home
510       directory;  thus `~ken' might expand to `/usr/ken' and `~ken/chmach' to
511       `/usr/ken/chmach'.  If the character `~' is  followed  by  a  character
512       other  than  a letter or `/' or appears not at the beginning of a word,
513       it is left undisturbed.
514
515       The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'.  Left to
516       right  order  is  preserved, with results of matches being sorted sepa‐
517       rately at a low level to preserve this order.  This  construct  may  be
518       nested.        Thus      `~source/s1/{oldls,ls}.c'      expands      to
519       `/usr/source/s1/oldls.c /usr/source/s1/ls.c' whether or not these files
520       exist without any chance of error if the home directory for `source' is
521       `/usr/source'.  Similarly `../{memo,*box}'  might  expand  to  `../memo
522       ../box  ../mbox'.  (Note that `memo' was not sorted with the results of
523       matching `*box'.)  As a special case  `{',  `}'  and  `{}'  are  passed
524       undisturbed.
525
526       Input/output
527
528       The  standard  input and standard output of a command may be redirected
529       with the following syntax:
530
531       < name
532            Open file name (which is  first  variable,  command  and  filename
533            expanded) as the standard input.
534
535       << word
536            Read  the  shell  input  up  to a line which is identical to word.
537            Word is not subjected to variable, filename or  command  substitu‐
538            tion, and each input line is compared to word before any substitu‐
539            tions are done on this input line.  Unless a quoting `\', `"', `''
540            or  ``'  appears in word variable and command substitution is per‐
541            formed on the intervening lines, allowing `\' to  quote  `$',  `\'
542            and  ``'.   Commands  which are substituted have all blanks, tabs,
543            and newlines preserved, except for  the  final  newline  which  is
544            dropped.   The  resultant text is placed in an anonymous temporary
545            file which is given to the command as standard input.
546
547       > name
548       >! name
549       >& name
550       >&! name
551            The file name is used as standard output.  If the  file  does  not
552            exist  then  it  is created; if the file exists, its is truncated,
553            its previous contents being lost.
554
555            If the variable noclobber is set, then the file must not exist  or
556            be a character special file (e.g. a terminal or `/dev/null') or an
557            error results.   This  helps  prevent  accidental  destruction  of
558            files.   In  this case the `!' forms can be used and suppress this
559            check.
560
561            The forms involving `&' route the diagnostic output into the spec‐
562            ified  file  as  well as the standard output.  Name is expanded in
563            the same way as `<' input filenames are.
564
565       >> name
566       >>& name
567       >>! name
568       >>&! name
569            Uses file name as standard output like `>' but  places  output  at
570            the end of the file.  If the variable noclobber is set, then it is
571            an error for the file not to exist unless one of the `!' forms  is
572            given.  Otherwise similar to `>'.
573
574       A  command  receives  the environment in which the shell was invoked as
575       modified by the input-output parameters and the presence of the command
576       in  a pipeline.  Thus, unlike some previous shells, commands run from a
577       file of shell commands have no access to the text of  the  commands  by
578       default;  rather they receive the original standard input of the shell.
579       The `<<' mechanism should be used to present inline data.  This permits
580       shell command scripts to function as components of pipelines and allows
581       the shell to block read its input.   Note  that  the  default  standard
582       input  for  a command run detached is not modified to be the empty file
583       `/dev/null'; rather the standard input remains as the original standard
584       input  of the shell.  If this is a terminal and if the process attempts
585       to read from the terminal, then the process will  block  and  the  user
586       will be notified (see Jobs above).
587
588       Diagnostic output may be directed through a pipe with the standard out‐
589       put.  Simply use the form `|&' rather than just `|'.
590
591       Expressions
592
593       A number of the builtin commands (to be  described  subsequently)  take
594       expressions, in which the operators are similar to those of C, with the
595       same precedence.  These expressions appear in  the  @,  exit,  if,  and
596       while commands.  The following operators are available:
597
598            ||   &&  |  ^  &  ==  !=  =~  !~  <=  >=  <  >  <<  >>  +  -  *  /
599       %  !  ~  (  )
600
601       Here the precedence increases to the right, `==' `!='  `=~'  and  `!~',
602       `<='  `>='  `<'  and  `>',  `<<' and `>>', `+' and `-', `*' `/' and `%'
603       being, in groups, at the same level.  The `==' `!=' `=~' and `!~' oper‐
604       ators  compare  their  arguments as strings; all others operate on num‐
605       bers.  The operators `=~' and `!~' are like `!=' and `=='  except  that
606       the  right  hand  side  is  a  pattern (containing, e.g. `*'s, `?'s and
607       instances of `[...]')  against which the left hand operand is  matched.
608       This  reduces the need for use of the switch statement in shell scripts
609       when all that is really needed is pattern matching.
610
611       Strings which begin with `0' are considered  octal  numbers.   Null  or
612       missing  arguments  are  considered `0'.  The result of all expressions
613       are strings, which represent decimal numbers.  It is important to  note
614       that  no  two  components of an expression can appear in the same word;
615       except when adjacent to components of expressions which  are  syntacti‐
616       cally  significant  to the parser (`&' `|' `<' `>' `(' `)') they should
617       be surrounded by spaces.
618
619       Also available in expressions as primitive operands are command  execu‐
620       tions enclosed in `{' and `}' and file enquiries of the form `-l  name'
621       where l is one of:
622
623            r    read access
624            w    write access
625            x    execute access
626            e    existence
627            o    ownership
628            z    zero size
629            f    plain file
630            d    directory
631
632       The specified name is command and filename expanded and then tested  to
633       see if it has the specified relationship to the real user.  If the file
634       does not exist or is inaccessible then all enquiries return false, i.e.
635       `0'.  Command executions succeed, returning true, i.e. `1', if the com‐
636       mand exits with status 0, otherwise they fail,  returning  false,  i.e.
637       `0'.   If more detailed status information is required then the command
638       should be executed outside of an expression  and  the  variable  status
639       examined.
640
641       Control flow
642
643       The  shell  contains a number of commands which can be used to regulate
644       the flow of control in command files (shell scripts)  and  (in  limited
645       but  useful  ways)  from terminal input.  These commands all operate by
646       forcing the shell to reread or skip in its input and, due to the imple‐
647       mentation, restrict the placement of some of the commands.
648
649       The  foreach, switch, and while statements, as well as the if-then-else
650       form of the if statement require that the major keywords  appear  in  a
651       single simple command on an input line as shown below.
652
653       If  the shell's input is not seekable, the shell buffers up input when‐
654       ever a loop is being read and performs seeks in this internal buffer to
655       accomplish the rereading implied by the loop.  (To the extent that this
656       allows, backward goto's will succeed on non-seekable inputs.)
657
658       Builtin commands
659
660       Builtin commands are executed within the shell.  If a  builtin  command
661       occurs  as  any component of a pipeline except the last then it is exe‐
662       cuted in a subshell.
663
664       alias
665       alias name
666       alias name wordlist
667            The first form prints all aliases.  The  second  form  prints  the
668            alias  for name.  The final form assigns the specified wordlist as
669            the alias of name; wordlist is command and  filename  substituted.
670            Name is not allowed to be alias or unalias.
671
672       alloc
673            Shows the amount of dynamic memory acquired, broken down into used
674            and free memory.  With an argument shows the number  of  free  and
675            used blocks in each size category.  The categories start at size 8
676            and double at each step.  This command's output  may  vary  across
677            system types, since systems other than the VAX may use a different
678            memory allocator.
679
680       bg
681       bg %job ...
682            Puts the current or specified jobs into the background, continuing
683            them if they were stopped.
684
685       break
686            Causes  execution to resume after the end of the nearest enclosing
687            foreach or while.  The remaining commands on the current line  are
688            executed.   Multi-level  breaks  are thus possible by writing them
689            all on one line.
690
691       breaksw
692            Causes a break from a switch, resuming after the endsw.
693
694       case label:
695            A label in a switch statement as discussed below.
696
697       cd
698       cd name
699       chdir
700       chdir name
701            Change the shell's working directory to  directory  name.   If  no
702            argument is given then change to the home directory of the user.
703            If  name  is  not found as a subdirectory of the current directory
704            (and does not begin with `/', `./' or `../'), then each  component
705            of  the variable cdpath is checked to see if it has a subdirectory
706            name.  Finally, if all else fails but name  is  a  shell  variable
707            whose  value begins with `/', then this is tried to see if it is a
708            directory.
709
710       continue
711            Continue execution of the nearest enclosing while or foreach.  The
712            rest of the commands on the current line are executed.
713
714       default:
715            Labels the default case in a switch statement.  The default should
716            come after all case labels.
717
718       dirs
719            Prints the directory stack; the top of the stack is at  the  left,
720            the first directory in the stack being the current directory.
721
722       echo wordlist
723       echo -n wordlist
724            The  specified  words  are  written to the shells standard output,
725            separated by spaces, and terminated with a newline unless  the  -n
726            option is specified.
727
728       else
729       end
730       endif
731       endsw
732            See  the  description of the foreach, if, switch, and while state‐
733            ments below.
734
735       eval arg ...
736            (As in sh(1).)  The arguments are read as input to the  shell  and
737            the  resulting  command(s)  executed in the context of the current
738            shell.  This is usually used to execute commands generated as  the
739            result  of  command or variable substitution, since parsing occurs
740            before these substitutions.  See tset(1) for an example  of  using
741            eval.
742
743       exec command
744            The specified command is executed in place of the current shell.
745
746       exit
747       exit(expr)
748            The  shell  exits  either  with  the  value of the status variable
749            (first form) or with the  value  of  the  specified  expr  (second
750            form).
751
752       fg
753       fg %job ...
754            Brings the current or specified jobs into the foreground, continu‐
755            ing them if they were stopped.
756
757       foreach name (wordlist)
758           ...
759       end
760            The variable name is successively set to each member  of  wordlist
761            and the sequence of commands between this command and the matching
762            end are executed.  (Both foreach and end must appear alone on sep‐
763            arate lines.)
764
765            The builtin command continue may be used to continue the loop pre‐
766            maturely and the builtin command  break  to  terminate  it  prema‐
767            turely.   When this command is read from the terminal, the loop is
768            read up once prompting with `?' before any statements in the  loop
769            are  executed.  If you make a mistake typing in a loop at the ter‐
770            minal you can rub it out.
771
772       glob wordlist
773            Like echo but no `\' escapes are recognized and words  are  delim‐
774            ited  by null characters in the output.  Useful for programs which
775            wish to use the shell to filename expand a list of words.
776
777       goto word
778            The specified word is filename and command  expanded  to  yield  a
779            string  of  the form `label'.  The shell rewinds its input as much
780            as possible and searches for a line of the form `label:'  possibly
781            preceded  by blanks or tabs.  Execution continues after the speci‐
782            fied line.
783
784       hashstat
785            Print a statistics line indicating how effective the internal hash
786            table  has  been  at  locating commands (and avoiding exec's).  An
787            exec is attempted for each component of the path  where  the  hash
788            function  indicates  a  possible  hit, and in each component which
789            does not begin with a `/'.
790
791       history
792       history n
793       history -r n
794       history -h n
795            Displays the history event list; if n is given  only  the  n  most
796            recent  events  are  printed.  The -r option reverses the order of
797            printout to be most recent first rather than oldest first.  The -h
798            option  causes the history list to be printed without leading num‐
799            bers.  This is used to produce files suitable for sourceing  using
800            the -h option to source.
801
802       if (expr) command
803            If  the  specified expression evaluates true, then the single com‐
804            mand with arguments is executed.  Variable substitution on command
805            happens  early,  at  the  same time it does for the rest of the if
806            command.  Command must be a simple command, not a pipeline, a com‐
807            mand  list,  or  a parenthesized command list.  Input/output redi‐
808            rection occurs even if expr is false, when command is not executed
809            (this is a bug).
810
811       if (expr) then
812           ...
813       else if (expr2) then
814           ...
815       else
816           ...
817       endif
818            If  the specified expr is true then the commands to the first else
819            are executed; otherwise if expr2 is true then the commands to  the
820            second  else  are  executed, etc.  Any number of else-if pairs are
821            possible; only one endif is needed.  The  else  part  is  likewise
822            optional.   (The words else and endif must appear at the beginning
823            of input lines; the if must appear alone  on  its  input  line  or
824            after an else.)
825
826       jobs
827       jobs -l
828            Lists  the active jobs; given the -l options lists process id's in
829            addition to the normal information.
830
831       kill %job
832       kill -sig %job ...
833       kill pid
834       kill -sig pid ...
835       kill -l
836            Sends either the TERM (terminate) signal or the  specified  signal
837            to  the  specified jobs or processes.  Signals are either given by
838            number or by names (as given in /usr/include/signal.h, stripped of
839            the  prefix ``SIG'').  The signal names are listed by ``kill -l''.
840            There is no default, saying just `kill' does not send a signal  to
841            the  current job.  If the signal being sent is TERM (terminate) or
842            HUP (hangup), then the job or process will be sent  a  CONT  (con‐
843            tinue) signal as well.
844
845       limit
846       limit resource
847       limit resource maximum-use
848       limit -h
849       limit -h resource
850       limit -h resource maximum-use
851            Limits  the consumption by the current process and each process it
852            creates to not individually exceed maximum-use  on  the  specified
853            resource.   If  no maximum-use is given, then the current limit is
854            printed; if no resource is given, then all limitations are  given.
855            If  the  -h flag is given, the hard limits are used instead of the
856            current limits.  The hard limits impose a ceiling on the values of
857            the  current  limits.  Only the super-user may raise the hard lim‐
858            its, but a user may lower or raise the current limits  within  the
859            legal range.
860
861            Resources controllable currently include cputime (the maximum num‐
862            ber of cpu-seconds to be used  by  each  process),  filesize  (the
863            largest  single  file which can be created), datasize (the maximum
864            growth of the data+stack region via sbrk(2) beyond the end of  the
865            program  text),  stacksize (the maximum size of the automatically-
866            extended stack region), and coredumpsize (the size of the  largest
867            core dump that will be created).
868
869            The maximum-use may be given as a (floating point or integer) num‐
870            ber followed by a scale factor.  For all limits other than cputime
871            the default scale is `k' or `kilobytes' (1024 bytes); a scale fac‐
872            tor of `m' or `megabytes' may  also  be  used.   For  cputime  the
873            default  scaling  is  `seconds',  while `m' for minutes or `h' for
874            hours, or a time of the form `mm:ss' giving  minutes  and  seconds
875            may be used.
876
877            For both resource names and scale factors, unambiguous prefixes of
878            the names suffice.
879
880       login
881            Terminate  a  login  shell,  replacing  it  with  an  instance  of
882            /bin/login.   This is one way to log off, included for compatibil‐
883            ity with sh(1).
884
885       logout
886            Terminate a login shell.  Especially useful if ignoreeof is set.
887
888       nice
889       nice +number
890       nice command
891       nice +number command
892            The first form sets the scheduling priority for this shell  to  4.
893            The  second form sets the priority to the given number.  The final
894            two forms run command at priority 4 and number respectively.   The
895            greater the number, the less cpu the process will get.  The super-
896            user may specify negative priority by using  `nice  -number  ...'.
897            Command  is  always  executed in a sub-shell, and the restrictions
898            placed on commands in simple if statements apply.
899
900       nohup
901       nohup command
902            The first form can be used in shell scripts to cause hangups to be
903            ignored  for  the remainder of the script.  The second form causes
904            the specified command to be run with hangups  ignored.   All  pro‐
905            cesses detached with `&' are effectively nohup'ed.
906
907       notify
908       notify %job ...
909            Causes the shell to notify the user asynchronously when the status
910            of the current or specified jobs changes; normally notification is
911            presented  before  a prompt.  This is automatic if the shell vari‐
912            able notify is set.
913
914       onintr
915       onintr  -
916       onintr  label
917            Control the action of the shell on  interrupts.   The  first  form
918            restores the default action of the shell on interrupts which is to
919            terminate shell scripts or to return to the terminal command input
920            level.   The  second  form  `onintr -' causes all interrupts to be
921            ignored.  The final form causes  the  shell  to  execute  a  `goto
922            label' when an interrupt is received or a child process terminates
923            because it was interrupted.
924
925            In any case, if the shell is running detached and  interrupts  are
926            being  ignored, all forms of onintr have no meaning and interrupts
927            continue to be ignored by the shell and all invoked commands.
928
929       popd
930       popd +n
931            Pops the directory stack, returning  to  the  new  top  directory.
932            With  an  argument  `+n' discards the nth entry in the stack.  The
933            elements of the directory stack are numbered from  0  starting  at
934            the top.
935
936       pushd
937       pushd name
938       pushd +n
939            With  no  arguments,  pushd  exchanges the top two elements of the
940            directory stack.  Given a name argument, pushd changes to the  new
941            directory  (ala  cd)  and pushes the old current working directory
942            (as in csw) onto the directory stack.  With  a  numeric  argument,
943            rotates  the  nth argument of the directory stack around to be the
944            top element and changes to it.  The members of the directory stack
945            are numbered from the top starting at 0.
946
947       rehash
948            Causes  the internal hash table of the contents of the directories
949            in the path variable to be recomputed.  This is needed if new com‐
950            mands  are  added  to directories in the path while you are logged
951            in.  This should only be necessary if you add commands to  one  of
952            your  own directories, or if a systems programmer changes the con‐
953            tents of one of the system directories.
954
955       repeat count command
956            The specified command which is subject to the same restrictions as
957            the  command in the one line if statement above, is executed count
958            times.  I/O redirections occur exactly once, even if count is 0.
959
960       set
961       set name
962       set name=word
963       set name[index]=word
964       set name=(wordlist)
965            The first form of the command shows the value of all  shell  vari‐
966            ables.   Variables  which  have  other than a single word as value
967            print as a parenthesized word list.  The second form sets name  to
968            the  null  string.   The  third form sets name to the single word.
969            The fourth form sets the index'th component of name to word;  this
970            component  must  already  exist.   The final form sets name to the
971            list of words in wordlist.  In all cases the value is command  and
972            filename expanded.
973
974            These arguments may be repeated to set multiple values in a single
975            set command.  Note however, that variable  expansion  happens  for
976            all arguments before any setting occurs.
977
978       setenv
979       setenv name value
980       setenv name
981            The  first form lists all current environment variables.  The last
982            form sets the value of environment variable name to  be  value,  a
983            single string.  The second form sets name to an empty string.  The
984            most commonly used environment variable USER, TERM, and  PATH  are
985            automatically  imported  to  and  exported  from the csh variables
986            user, term, and path; there is no need to use setenv for these.
987
988       shift
989       shift variable
990            The members of argv are shifted to the left,  discarding  argv[1].
991            It  is  an  error  for argv not to be set or to have less than one
992            word as value.  The second form performs the same function on  the
993            specified variable.
994
995       source name
996       source -h name
997            The  shell  reads  commands  from  name.   Source  commands may be
998            nested; if they are nested too deeply the shell  may  run  out  of
999            file  descriptors.   An  error in a source at any level terminates
1000            all nested source commands.  Normally input during source commands
1001            is  not  placed on the history list; the -h option causes the com‐
1002            mands to be placed in the history list without being executed.
1003
1004       stop
1005       stop %job ...
1006            Stops the current or specified job which is executing in the back‐
1007            ground.
1008
1009       suspend
1010            Causes  the  shell  to  stop in its tracks, much as if it had been
1011            sent a stop signal with ^Z.  This  is  most  often  used  to  stop
1012            shells started by su(1).
1013
1014       switch (string)
1015       case str1:
1016           ...
1017         breaksw
1018       ...
1019       default:
1020           ...
1021         breaksw
1022       endsw
1023            Each  case  label  is  successively matched, against the specified
1024            string which is first command and  filename  expanded.   The  file
1025            metacharacters  `*',  `?'  and  `[...]'  may  be  used in the case
1026            labels, which are variable expanded.  If none of the labels  match
1027            before a `default' label is found, then the execution begins after
1028            the default label.  Each case label and  the  default  label  must
1029            appear  at  the  beginning  of a line.  The command breaksw causes
1030            execution to continue after the endsw.  Otherwise control may fall
1031            through  case  labels  and  default  labels  as in C.  If no label
1032            matches and there is no default,  execution  continues  after  the
1033            endsw.
1034
1035       time
1036       time command
1037            With  no  argument,  a  summary of time used by this shell and its
1038            children is printed.  If arguments are given the specified  simple
1039            command  is  timed  and a time summary as described under the time
1040            variable is printed.  If necessary, an extra shell is  created  to
1041            print the time statistic when the command completes.
1042
1043       umask
1044       umask value
1045            The  file  creation  mask  is displayed (first form) or set to the
1046            specified value (second form).  The mask is given in octal.   Com‐
1047            mon values for the mask are 002 giving all access to the group and
1048            read and execute access to others or 022 giving all access  except
1049            no write access for users in the group or others.
1050
1051       unalias pattern
1052            All aliases whose names match the specified pattern are discarded.
1053            Thus all aliases are removed by `unalias *'.  It is not  an  error
1054            for nothing to be unaliased.
1055
1056       unhash
1057            Use  of the internal hash table to speed location of executed pro‐
1058            grams is disabled.
1059
1060       unlimit
1061       unlimit resource
1062       unlimit -h
1063       unlimit -h resource
1064            Removes the limitation on resource.  If no resource is  specified,
1065            then  all  resource  limitations are removed.  If -h is given, the
1066            corresponding hard limits are removed.  Only the super-user may do
1067            this.
1068
1069       unset pattern
1070            All variables whose names match the specified pattern are removed.
1071            Thus all variables are removed by `unset *'; this  has  noticeably
1072            distasteful  side-effects.   It  is not an error for nothing to be
1073            unset.
1074
1075       unsetenv pattern
1076            Removes all variables whose name match the specified pattern  from
1077            the  environment.   See  also  the setenv command above and print‐
1078            env(1).
1079
1080       wait
1081            All background jobs are waited for.  It the shell is  interactive,
1082            then  an  interrupt  can disrupt the wait, at which time the shell
1083            prints names and job numbers of all jobs known to be outstanding.
1084
1085       while (expr)
1086           ...
1087       end
1088            While the specified expression evaluates  non-zero,  the  commands
1089            between  the  while and the matching end are evaluated.  Break and
1090            continue may be used to terminate  or  continue  the  loop  prema‐
1091            turely.   (The  while  and  end  must  appear alone on their input
1092            lines.)  Prompting occurs here the first time through the loop  as
1093            for the foreach statement if the input is a terminal.
1094
1095       %job
1096            Brings the specified job into the foreground.
1097
1098       %job &
1099            Continues the specified job in the background.
1100
1101       @
1102       @ name = expr
1103       @ name[index] = expr
1104            The  first form prints the values of all the shell variables.  The
1105            second form sets the specified name to the value of expr.  If  the
1106            expression  contains  `<', `>', `&' or `|' then at least this part
1107            of the expression must be placed within `(' `)'.  The  third  form
1108            assigns  the value of expr to the index'th argument of name.  Both
1109            name and its index'th component must already exist.
1110
1111            The operators `*=', `+=', etc are available as in  C.   The  space
1112            separating  the  name  from  the  assignment operator is optional.
1113            Spaces are, however, mandatory in separating  components  of  expr
1114            which would otherwise be single words.
1115
1116            Special  postfix  `++'  and `--' operators increment and decrement
1117            name respectively, i.e. `@  i++'.
1118
1119       Pre-defined and environment variables
1120
1121       The following variables have special meaning to the shell.   Of  these,
1122       argv,  cwd,  home, path, prompt, shell and status are always set by the
1123       shell.  Except for cwd and status this setting occurs only at  initial‐
1124       ization;  these variables will not then be modified unless this is done
1125       explicitly by the user.
1126
1127       This shell copies the environment variable USER into the variable user,
1128       TERM  into  term,  and  HOME  into home, and copies these back into the
1129       environment whenever the normal shell variables are reset.   The  envi‐
1130       ronment variable PATH is likewise handled; it is not necessary to worry
1131       about its setting other than in the file .cshrc as  inferior  csh  pro‐
1132       cesses will import the definition of path from the environment, and re-
1133       export it if you then change it.
1134
1135       argv           Set to the arguments to the shell, it is from this vari‐
1136                      able  that  positional  parameters are substituted, i.e.
1137                      `$1' is replaced by `$argv[1]', etc.
1138
1139       cdpath         Gives a list of alternate directories searched  to  find
1140                      subdirectories in chdir commands.
1141
1142       cwd            The full pathname of the current directory.
1143
1144       echo           Set  when  the  -x command line option is given.  Causes
1145                      each command and its arguments to be echoed just  before
1146                      it is executed.  For non-builtin commands all expansions
1147                      occur  before  echoing.   Builtin  commands  are  echoed
1148                      before  command  and  filename substitution, since these
1149                      substitutions are then done selectively.
1150
1151       filec          Enable file name completion.
1152
1153       histchars      Can be given a string value  to  change  the  characters
1154                      used  in  history  substitution.  The first character of
1155                      its value is used as the history substitution character,
1156                      replacing the default character !.  The second character
1157                      of its value replaces the character ↑ in quick substitu‐
1158                      tions.
1159
1160       history        Can  be given a numeric value to control the size of the
1161                      history list.  Any command which has been referenced  in
1162                      this  many events will not be discarded.  Too large val‐
1163                      ues of history may run the shell  out  of  memory.   The
1164                      last  executed  command  is  always saved on the history
1165                      list.
1166
1167       home           The home directory of the invoker, initialized from  the
1168                      environment.   The  filename  expansion of `~' refers to
1169                      this variable.
1170
1171       ignoreeof      If set the shell ignores end-of-file from input  devices
1172                      which are terminals.  This prevents shells from acciden‐
1173                      tally being killed by control-D's.
1174
1175       mail           The files where the shell checks for mail.  This is done
1176                      after  each  command  completion  which will result in a
1177                      prompt, if a specified interval has elapsed.  The  shell
1178                      says  `You  have  new mail.'  if the file exists with an
1179                      access time not greater than its modify time.
1180
1181                      If the first word of the value of  mail  is  numeric  it
1182                      specifies  a  different  mail checking interval, in sec‐
1183                      onds, than the default, which is 10 minutes.
1184
1185                      If multiple mail files are  specified,  then  the  shell
1186                      says  `New  mail in name' when there is mail in the file
1187                      name.
1188
1189       noclobber      As described in the section  on  Input/output,  restric‐
1190                      tions  are  placed  on output redirection to insure that
1191                      files are not  accidentally  destroyed,  and  that  `>>'
1192                      redirections refer to existing files.
1193
1194       noglob         If  set,  filename expansion is inhibited.  This is most
1195                      useful in shell scripts which are not dealing with file‐
1196                      names,  or  after  a list of filenames has been obtained
1197                      and further expansions are not desirable.
1198
1199       nonomatch      If set, it is not an error for a filename  expansion  to
1200                      not  match any existing files; rather the primitive pat‐
1201                      tern is returned.  It is still an error for  the  primi‐
1202                      tive pattern to be malformed, i.e.  `echo [' still gives
1203                      an error.
1204
1205       notify         If set, the shell notifies asynchronously of job comple‐
1206                      tions.  The default is to rather present job completions
1207                      just before printing a prompt.
1208
1209       path           Each word of the path variable specifies a directory  in
1210                      which  commands  are to be sought for execution.  A null
1211                      word specifies the current directory.  If  there  is  no
1212                      path  variable  then  only full path names will execute.
1213                      The usual search path is `.', `/bin' and `/usr/bin', but
1214                      this may vary from system to system.  For the super-user
1215                      the default search path is `/bin', `/sbin', `/usr/sbin',
1216                      and  `/usr/bin'.   A shell which is given neither the -c
1217                      nor the -t option will normally hash the contents of the
1218                      directories  in  the path variable after reading .cshrc,
1219                      and each time the path variable is reset.  If  new  com‐
1220                      mands  are added to these directories while the shell is
1221                      active, it may be necessary to give the  rehash  or  the
1222                      commands may not be found.
1223
1224       prompt         The  string which is printed before each command is read
1225                      from an interactive terminal input.  If a `!' appears in
1226                      the string it will be replaced by the current event num‐
1227                      ber unless a preceding `\' is given.  Default is  `%  ',
1228                      or `# ' for the super-user.
1229
1230       savehist       is  given  a  numeric  value  to  control  the number of
1231                      entries of the history list that are saved in ~/.history
1232                      when the user logs out.  Any command which has been ref‐
1233                      erenced in this many events will be saved.  During start
1234                      up  the  shell  sources ~/.history into the history list
1235                      enabling history to be saved across logins.   Too  large
1236                      values of savehist will slow down the shell during start
1237                      up.
1238
1239       shell          The file in which the shell resides.  This  is  used  in
1240                      forking  shells  to  interpret  files which have execute
1241                      bits set, but which are not executable  by  the  system.
1242                      (See  the  description  of Non-builtin Command Execution
1243                      below.)  Initialized to the (system-dependent)  home  of
1244                      the shell.
1245
1246       status         The  status  returned by the last command.  If it termi‐
1247                      nated abnormally, then 0200  is  added  to  the  status.
1248                      Builtin  commands which fail return exit status `1', all
1249                      other builtin commands set status `0'.
1250
1251       time           Controls automatic timing of commands.  If set, then any
1252                      command which takes more than this many cpu seconds will
1253                      cause a line giving user, system, and real times  and  a
1254                      utilization  percentage  which is the ratio of user plus
1255                      system times to real time to be printed when  it  termi‐
1256                      nates.
1257
1258       verbose        Set  by  the -v command line option, causes the words of
1259                      each command to be printed after history substitution.
1260
1261       Non-builtin command execution
1262
1263       When a command to be executed is found to not be a builtin command  the
1264       shell  attempts to execute the command via execve(2).  Each word in the
1265       variable path names a directory from which the shell  will  attempt  to
1266       execute  the command.  If it is given neither a -c nor a -t option, the
1267       shell will hash the names in these directories into an  internal  table
1268       so that it will only try an exec in a directory if there is a possibil‐
1269       ity that the command resides there.  This greatly speeds command  loca‐
1270       tion when a large number of directories are present in the search path.
1271       If this mechanism has been turned off (via unhash), or if the shell was
1272       given a -c or -t argument, and in any case for each directory component
1273       of path which does not begin with a `/', the  shell  concatenates  with
1274       the  given  command  name  to  form a path name of a file which it then
1275       attempts to execute.
1276
1277       Parenthesized commands are always executed in a subshell.  Thus `(cd  ;
1278       pwd)  ;  pwd'  prints  the  home  directory; leaving you where you were
1279       (printing this after the home directory), while `cd ; pwd'  leaves  you
1280       in  the  home directory.  Parenthesized commands are most often used to
1281       prevent chdir from affecting the current shell.
1282
1283       If the file has execute permissions but is not an executable binary  to
1284       the  system,  then it is assumed to be a file containing shell commands
1285       and a new shell is spawned to read it.
1286
1287       If there is an alias for shell then the words  of  the  alias  will  be
1288       prepended  to  the  argument list to form the shell command.  The first
1289       word of the alias should be the full  path  name  of  the  shell  (e.g.
1290       `$shell').   Note that this is a special, late occurring, case of alias
1291       substitution, and only allows words to be  prepended  to  the  argument
1292       list without modification.
1293
1294       Argument list processing
1295
1296       If argument 0 to the shell is `-' then this is a login shell.  The flag
1297       arguments are interpreted as follows:
1298
1299       -b   This flag forces a ``break'' from option processing,  causing  any
1300            further  shell  arguments  to  be treated as non-option arguments.
1301            The remaining arguments will not be interpreted as shell  options.
1302            This  may be used to pass options to a shell script without confu‐
1303            sion or possible subterfuge.  The shell will not run a set-user ID
1304            script without this option.
1305
1306       -c   Commands  are read from the (single) following argument which must
1307            be present.  Any remaining arguments are placed in argv.
1308
1309       -e   The shell exits if any invoked command  terminates  abnormally  or
1310            yields a non-zero exit status.
1311
1312       -f   The  shell  will  start faster, because it will neither search for
1313            nor execute commands from the file `.cshrc' in the invoker's  home
1314            directory.
1315
1316       -i   The shell is interactive and prompts for its top-level input, even
1317            if it appears to not be a terminal.  Shells are interactive  with‐
1318            out this option if their inputs and outputs are terminals.
1319
1320       -n   Commands  are  parsed,  but  not executed.  This aids in syntactic
1321            checking of shell scripts.
1322
1323       -s   Command input is taken from the standard input.
1324
1325       -t   A single line of input is read and executed.  A `\' may be used to
1326            escape  the  newline  at  the  end  of this line and continue onto
1327            another line.
1328
1329       -v   Causes the verbose variable to be set, with the effect  that  com‐
1330            mand input is echoed after history substitution.
1331
1332       -x   Causes  the  echo  variable to be set, so that commands are echoed
1333            immediately before execution.
1334
1335       -V   Causes the verbose variable to be set even before `.cshrc' is exe‐
1336            cuted.
1337
1338       -X   Is to -x as -V is to -v.
1339
1340       After processing of flag arguments, if arguments remain but none of the
1341       -c, -i, -s, or -t options was given, the first argument is taken as the
1342       name  of a file of commands to be executed.  The shell opens this file,
1343       and saves its name for possible resubstitution  by  `$0'.   Since  many
1344       systems  use  either  the  standard version 6 or version 7 shells whose
1345       shell scripts are not compatible with this shell, the shell  will  exe‐
1346       cute  such a `standard' shell if the first character of a script is not
1347       a `#', i.e. if the script does not start  with  a  comment.   Remaining
1348       arguments initialize the variable argv.
1349
1350       Signal handling
1351
1352       The shell normally ignores quit signals.  Jobs running detached (either
1353       by `&' or the bg or %... & commands) are immune  to  signals  generated
1354       from  the  keyboard,  including hangups.  Other signals have the values
1355       which the shell inherited from its  parent.   The  shells  handling  of
1356       interrupts  and terminate signals in shell scripts can be controlled by
1357       onintr.  Login shells catch the terminate signal; otherwise this signal
1358       is  passed  on to children from the state in the shell's parent.  In no
1359       case are interrupts allowed when a login  shell  is  reading  the  file
1360       `.logout'.
1361

AUTHOR

1363       William  Joy.   Job  control  and directory stack features first imple‐
1364       mented by J.E. Kulp of I.I.A.S.A, Laxenburg,  Austria,  with  different
1365       syntax  than  that  used now.  File name completion code written by Ken
1366       Greer, HP Labs.
1367

FILES

1369       ~/.cshrc         Read at beginning of execution by each shell.
1370       ~/.login         Read by login shell, after `.cshrc' at login.
1371       ~/.logout        Read by login shell, at logout.
1372       /bin/sh          Standard shell, for shell scripts not starting with a `#'.
1373       /tmp/sh*         Temporary file for `<<'.
1374       /etc/passwd      Source of home directories for `~name'.
1375

LIMITATIONS

1377       Words can be no longer than 1024 characters.  The system  limits  argu‐
1378       ment  lists  to 10240 characters.  The number of arguments to a command
1379       which involves filename expansion is limited to 1/6'th  the  number  of
1380       characters allowed in an argument list.  Command substitutions may sub‐
1381       stitute no more characters than are allowed in an  argument  list.   To
1382       detect  looping,  the shell restricts the number of alias substitutions
1383       on a single line to 20.
1384

SEE ALSO

1386       sh(1), access(2), execve(2), fork(2),  killpg(2),  pipe(2),  sigvec(2),
1387       umask(2),  setrlimit(2),  wait(2),  tty(4),  a.out(5),  environ(7), `An
1388       introduction to the C shell'
1389

BUGS

1391       When a command is restarted from a stop, the shell prints the directory
1392       it started in if this is different from the current directory; this can
1393       be misleading (i.e. wrong) as the  job  may  have  changed  directories
1394       internally.
1395
1396       Shell   builtin   functions  are  not  stoppable/restartable.   Command
1397       sequences of the form `a ; b ; c' are also not handled gracefully  when
1398       stopping is attempted.  If you suspend `b', the shell will then immedi‐
1399       ately execute `c'.  This is especially  noticeable  if  this  expansion
1400       results  from  an alias.  It suffices to place the sequence of commands
1401       in ()'s to force it to a subshell, i.e. `( a ; b ; c )'.
1402
1403       Control over tty output after processes are started is primitive;  per‐
1404       haps  this  will  inspire  someone  to  work on a good virtual terminal
1405       interface.  In a  virtual  terminal  interface  much  more  interesting
1406       things could be done with output control.
1407
1408       Alias substitution is most often used to clumsily simulate shell proce‐
1409       dures; shell procedures should be provided rather than aliases.
1410
1411       Commands within loops, prompted for by `?', are not placed in the  his‐
1412       tory list.  Control structure should be parsed rather than being recog‐
1413       nized as built-in commands.  This would allow control  commands  to  be
1414       placed  anywhere,  to be combined with `|', and to be used with `&' and
1415       `;' metasyntax.
1416
1417       It should be possible to use the `:' modifiers on the output of command
1418       substitutions.  All and more than one `:' modifier should be allowed on
1419       `$' substitutions.
1420
1421       The way the filec facility is implemented is ugly and expensive.
1422
1423
1424
14254th Berkeley Distribution      November 27, 1996                        CSH(1)
Impressum