User Guide

Getting Started

Starting Hamilton C shell is as simple as just double-clicking the icon. After the initial greeting, you’ll see the first prompt: (The underscore is meant to be the cursor.)

Hamilton C shell(tm) Release 3.0
Copyright (c) 1988-2003 by Hamilton Laboratories. 
1 D% _

This tells you that it will remember what you type as command number 1 and that your current drive is D (or whatever it is on your machine.) The “%” is traditional; rather like the “>” for Windows Command Prompt. Naturally, you can change your prompt if you want, to be anything you like. For example, to get a prompt that looks like one you might get from cmd.exe:

1 D% set prompt1 = '$cwd> '
d:\Program Files\Hamilton C shell 2003> _

This works by taking the value of the cwd (current working directory) variable and pasting a “>” and a space onto the end. The value is recalculated each time a prompt is given, so it always displays an up-to-date value. (Lists of all the built-in variables and procedures are given in later sections.)

To set it back:

d:\Program Files\Hamilton C shell 2003> unset prompt1
3 D% _

Basic Statements

Generally speaking, whatever commands you might have typed into cmd.exe (or command.com) will still work here. Even an “internal” cmd.exe function like dir works:

3 D% dir
 Volume in drive D is Nicole
 Volume Serial Number is 70AE-6E52

 Directory of d:\Program Files\Hamilton C shell 2003

07/01/2003  01:33 AM    <DIR>          .
07/01/2003  01:33 AM    <DIR>          ..
06/30/2003  09:05 AM    <DIR>          Bin
08/30/1998  12:28 PM             1,500 login.csh
06/29/2003  07:28 PM           161,311 ReleaseNotes.txt
06/30/2003  09:05 AM    <DIR>          Samples
06/30/2003  12:07 AM             6,416 startup.csh
06/30/2003  09:05 AM    <DIR>          Userguide
08/30/1998  05:48 AM             2,082 vi-perl.txt
               4 File(s)        171,309 bytes
               5 Dir(s)  28,619,657,216 bytes free
4 D% _

If the command you type refers to a .cmd batch file or a cmd.exe internal function, Hamilton C shell passes it to a child process running cmd.exe for evaluation. (cmd.exe’s built-in functions are intercepted with aliases defined in your startup.csh file.) Everything else is evaluated directly by Hamilton C shell. For example, if you type the name of an .exe file, the appropriate CreateProcess( ) call to the NT kernel to start that program will be done directly by Hamilton C shell.

A bit-mapped hash mechanism is used so that when you type the name of a command, the shell zeroes right in on file you mean. It doesn’t have to check every path directory for every possible extension. Naturally, if you type a command that doesn’t exist, the shell complains:

4 D% zork
csh:  Couldn't find an executable file named 'zork'.

By being more than merely a “wrapper” around an existing command processor, several advantages are created: (1) performance is understandably (and visibly!) much higher and (2) limitations on command line lengths, etc., become the relatively generous limits of Windows, rather than the restrictive limits of cmd.exe.

Customizing the Screen Colors

The C shell’s default screen colors are white characters on a blue background. Highlighting and color are used to make some things (special files, etc.) stand out. All the use of color or highlighting is completely customizable. You can choose anything you like. The chapter on customization will go into this in detail, but for now, let’s suppose we’d simply like to pick something a little different, like black characters on a bright white background:

5 D% setenv COLORS = black on bright white

Command Line Editing

With command line editing, you’ll notice immediately how much easier it is do things quickly without a lot of retyping. As you try the examples, notice how the arrow, insert, delete, home, end and other keys can be used to recall previous commands or make changes anywhere on the line.

Command line editing is like having a full-screen editor pasted onto the front end of the shell. Key bindings are intuitive and follow accepted conventions. You can create enormous commands that stretch over screen after screen and move around with the arrow keys, inserting or deleting anywhere. Watch changes ripple almost instantly down even an entire screenful of text. We think you’ll find our command line editing superior to anything you’ve seen or used elsewhere.

The basic key assignments are:

<Insert>	Toggle between insert and overstrike modes. (The cursor is thicker when you’re inserting.)
<Home> <End>	Beginning/end of command line.
<Left> <Right>	One character left/right.
<Up> <Down>	Up/down one command in the history list.

Pressing Ctrl with the arrow keys lets you move by words or lines. Pressing Alt instead does word or line deletion. (The convention we follow is that the Alt key is a little “more powerful” than the Ctrl key.)

What you last deleted is kept in a scrap buffer and can be pasted back elsewhere. To paste something from the scrap buffer back into the command line, move the cursor to where you want it done and press:

Ctrl-<Insert>	Paste one word at a time.
Alt-<Insert>	Paste the whole thing.

Command Completion

In addition to backing up through your previous commands one at a time with <Up> and <Down>, you can also ask the shell to search back through any previous commands you’ve typed for the last command that either started with or contained the characters in the previous word.

Ctrl-<Enter>	means “look for a command that started with ...,” and
Ctrl-Shift-<Enter>	(again, a little “stronger”) means “look for a command that contained the string anywhere.” (It’s necessary to type Ctrl-Shift-<Enter> because Alt-<Enter> is grabbed by the system to mean switch to full-screen.)

Repeatedly pressing these keys cycles up through all the matching commands you’ve previously typed. Command completion uses something called the history mechanism to recall commands you’ve previously typed. Later, we’ll devote a whole chapter to some of the more advanced uses of history.

Filename Completion

Filename completion is another “creature comfort:” you type just a fragment of a filename and let the shell fill in the rest. There are three variations: using the F key for basic filename completion, the D key if you want all the duplicates listed and the Tab key for walking one-by-one through the list of matches.

Alt-F or Ctrl-F	Filename completion. Look for a filename that starts with preceding characters. If it matches a single file, fill in the rest of the name. If more than one file matched, show the part that was the same for all, highlighted in green. (Bright red means there were no matches at all.)
Alt-D or Ctrl-D	Duplicate completions. Show any/all matching filenames, one after the other with spaces between.
<Tab>	Next match. Show the new match in the list of filenames that match the wildcard, replacing the previous match. After the last match, put the original string back up, highlighting it in bright red, then continue cycling through the list again.
Shift-<Tab>	Previous match. Same as the <Tab> key, but rotate backward through the list of matches.

(Since <Tab> is normally bound to the filename completion function, the regular tab character is typed instead as Ctrl-<Tab>. If you’d prefer to have the <Tab> key be the regular tab character and Ctrl-<Tab> be filename completion, invoke the C shell with the -T option.)

Filename completion is done with wildcarding, pasting an "*" onto the end of the previous word and then looking for any matches. Unlike cmd.exe, Hamilton C shell does any wildcarding before executing the command you type. It uses a powerful recursive pattern match algorithm that guarantees sensible matches even if you type a very complex pattern. Wildcarding is the subject of a whole chapter up ahead.

The Tour Begins Here

The following chapters introduce the various facilities Hamilton C shell provides, starting with some of its basic vocabulary: the simple utilities that come with it.

Following discussion shifts to the intrinsic, internal functions provided by the shell itself: i/o redirection, pipes and command substitution; the history mechanism and wildcarding.

Intermediate level discussion follows, describing expressions, variables and aliases and the editing and quoting facilities. The process and thread scheduling mechanism is described, outlining how an activity can be placed in the background.

The tour will then cross the threshold from discussion of individual statements to discussion of structures of statements. Structures for iteration and condition-testing and procedural abstraction will be introduced.

Finally, we’ll wrap up with discussion of how to customize the shell together with a section detailing specific compatibility issues between the Hamilton and original Berkeley C shells.