-----------------------------------------------------------------------------
To prevent Cygwin applications from expanding wildcards, set the environment
variable CYGWIN to "noglob".  i.e., in your .tcshrc, put a line like this:

setenv CYGWIN noglob

(Cygwin applications assume that if they are not started from a shell
using the Cygwin runtime, the parent shell does not have the ability to glob.
This is visible as tcsh apparently expanding wildcards for quoted arguments.)

-----------------------------------------------------------------------------

All paths MUST be '/'-delimited. Do not expect the shell to work with
DOS-style paths.


Compiling:
---------

tcsh currently only compiles with Microsoft Visual C++ (2.0 and greater) on 
x86 or Alpha platforms. Simply copy system/win32 to config.h and
win32/makefile.win32 to the base directory.

run nmake -f makefile.win32


(Note: This distribution does not have a VC project. To compile the shell,
you will need to open a cmd.exe/command.com window, run vcvars32.bat from
your VC bin subdirectory and then run nmake as above).



Known Bugs:
----------
* Horizontal scrolling is completely busted.
* The 'time' builtin does not work.

* There is a hard limit of 64Kb on the size of the command line. This is
  an os-specific limit and cannot be changed.

* Launching applications via explorer associations is slow if the argument
  list is large.
 
-----------------------------------------------------------------------------
* This section only documents features specific to Windows NT/95 or 
* behaviour that is different from the Unix version. For complete tcsh
* documentation, please read the man pages or html docs.
-----------------------------------------------------------------------------

Version numbers below refer to the tail end of the $version variable,
containing the NT-specific version. For example,

tcsh 6.09.00 (Astron) 1999-08-16 (i586-Microsoft-Windows2000) options 8b,nls,dl,hb,color,nt-rev-5.40

In this case, the NT-specific version is 5.40


Environment Variables:
---------------------
Environment variables are case-insensitive on NT. tcsh as of 5.33 has
also been changed to reflect this behaviour. Thus,

setenv FOO bar

and,

setenv foo bar

are equivalent.

Note that the *value* is, of course, not case-insensitive.


Features
--------

* No backgrounding/job control. Use 'start' instead

  You can also use 
  <foo> & 
  or,
  nohup <foo> &

  where <foo> is some arbitrary command.

DO NOT start console apps with & unless u want them to read/write to your
console.  (A "console app" is any 32-bit application that is not GUI based.)

(nohup foo & will say "foo Done" pretty quickly, but ignore that. There is no
way for the shell to know when the nohupped process dies. Your job may still
be running in the background.)

* Filenames in the directories under WINNT (or WINDOWS or whatever you call
  your windows directory) are hashed only if they are .EXE.
  Names which are uppercase (For example, CALC.EXE) will also be hashed as
  lowercase,without extension. Thus, "where calc" as well as 
  "where CALC.EXE" will work.

(Explanation: tcsh uses a hashtable to track the location of executables. By
default on Unix, all the files in every path element are hashed. Since the
SystemRoot on NT has hundreds of junk files, tcsh will only hash .EXE files.
This hashing is, of course, case-sensitive. Thus CALC.EXE hashes to a
different value than calc.exe would. To enable the shell to work in a Windows
environment, tcsh will hash CALC.EXE as CALC.EXE as well as "calc").


Special Variables
-----------------
* oldtitle: 

  Stores the previous value of the console title, when you use
  the title builtin below. Use it like so:

	 title "$oldtitle"

  to restore the previous title.

* NTlamepathfix: 

  When set,  '/'-s in the PATH environment variable will be
  changed to '\'.  This helps applications started within tcsh that may
  not handle Unix-style PATHs.

* NTslowexec: 

 When set, this variable disables attempts to save a fork() by
 directly executing simple commands. "Simple" command means one which is
 interactive and not piped, niced, nohupped etc. redirecting output of
 a command also disables this optimization. 

 Since this shortcut feature is new, the variable provides a way to retain
 backward compatibility. It may be taken out at some time in the future, if
 the shell is found to be stable enough.

 If you see problems like the shell seeming to expand wildcards when it
 shouldn't, or other substitutions which should be quoted, set this
 variable and see if that fixes the problem.

* NTnoquoteprotect:

  Ordinarily , if you pass a double quote to a command string, tcsh 
  will protect the quotes by adding backslashes. For example,
  
  find . -name '"*.c"' 
  would get executed as 

  find . -name \"*.c\"

  Some applications (MKS find, for example) do not like the '\'. To
  prevent tcsh from quoting such arguments, set this variable.

  Of course, it may cause other applications to break, so use at
  your own risk.

* NTcaseifypwd:

  If set, corrects case of current directory when cd'ing into it. Apparently,
  some "filesystems" can't handle the default behaviour. Only works on
  Windows NT.

* TCSHSUBSTHB (Environment, NOT shell variable): 

  Specifies mappings for hashbang emulation. Should be ';'-separated pairs 
  of blank-separated mappings.

  For example,

     setenv TCSHSUBSTHB "/usr/local/bin/perl c:/bin/perl.exe;"

  will substitute #!c:/bin/perl.exe for scripts which have
  #!/usr/local/bin/perl at the top.

  The final ';' MUST be included. I don't check for errors too
  carefully, so it's up to you to supply the exact sequence.
  There is a hardcoded limit of 20 such pairs.


* TCSHONLYSTARTEXES (Environment variable): 

  Can be set on the fly and controls whether associations will be tried 
  for non-executables. 
  
  ("Associations" here means Explorer file-type associations, that cause,
  for example, Microsoft Word to be launched when you type "foo.doc" at
  a command prompt. That can have unexpected side-effects like batch files
  and perl scripts launching in another window when run from tcsh. )

  Any changes to this variable will NOT affect the the "start" builtin. 
  This builtin ALWAYS launches associations, since the whole point of 
  using "start" is to not block the current shell.

  You can also supply a semi-colon-separated list of extensions for 
  which to NOT try associations. For example, if the variable is set to

  "cmd;bat",
  
  .cmd/.bat files will be executed in the same window because the default 
  association is not used, instead an internal hack feeds them to the 
  DOS command processor.

  If the file extension does not match the list, the shell will try to 
  launch an association.

  o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-

  To achieve the old behaviour of this setting, you must set the
  variable to a 1-character value.i.e.,

  setenv TCSHONLYSTARTEXES 

  should be replaced by

  setenv TCSHONLYSTARTEXES 1

  This setting, as before, will prevent tcsh from trying associations
  for ANY non-executable.

  (a zero-length setting will not work. A length greater than 1 will 
  be assumed to be a list of extensions as above.)

  o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-o-

 

* TCSH_NOASYNCGUI (Enviroment variable): 

  Makes tcsh wait for win32 GUI apps to terminate, instead of returning 
  immediately.  This affects child processes, so it can be set/unset in 
  the parent shell at any point.


NT-specific Builtins
--------------------
* start: like cmd.exe's start
* title: change the shell title
* cls: Clear the entire console buffer instead of just the visible window.

Notes:
-----
* You should probably get the Cygwin utilities from http://cygwin.com

  Things like 'ls' and 'cat' are useful, since we don't have a 'type' or 'dir'
  anymore. 'ls' is pretty much a requirement unless you never do  'ls -l'.


* It should be pointed out that there is also a Cygwin version of tcsh that 
  will compile with gcc and provide all the other features emulated by the
  Cygwin runtime (like job control, signals, etc.). So, if you are looking for
  a way to pretend that you are on Unix, you should use that version.
  The same holds true for UWIN as well.


Startup Files:
--------------


 getenv(USERPROFILE)/.tcshrc

This can be overridden by setting HOME in the user's environment


* TCSHLANG: NLS support

You can get messages in a specific language by doing:

    setenv TCSHLANG <dll>, where <dll> is the name of the NLS dll.

tcsh comes with:

	tcshde.dll -> German
	tcshfr.dll -> French
	tcshsp.dll -> Spanish
	tcsh-it.dll -> Italian

	tcshc.dll  => Default "C" locale

You can change the dll at runtime by setting/unsetting this variable.

You can specify the DLL name, or the complete path, if it is not in your
standard search path.

(Using tcshc.dll is useless and adds unnecessary overhead. If you are
using English versions, do not install the dlls)


Virtual key code bindings:
-------------------------
To use keys like function keys, arrows, insert, etc., the following 
form of bindkey must be used:

bindkey -b N-xxx <command>

where xxx is either:
	a) A number from 1 through 24, representing the fucntion keys.
	For example, bindkey -b N-1 run-help

	b) The strings "pgup","pgdown","end","home", "left","up","right","down",
	"ins","del"
	For example, bindkey -b N-del delete-char

Here are the bindings I use in my .tcshrc:

# NT specific bindkey extensions
	bindkey -b N-up up-history           
	bindkey -b N-down down-history      
	bindkey -b N-right forward-char    
	bindkey -b N-left backward-char
	bindkey -b N-del delete-char
	bindkey -b N-ins overwrite-mode
	bindkey -b N-1 which-command
	bindkey -b N-2 expand-history
	bindkey -b N-3 complete-word-raw
	bindkey -b N-home beginning-of-line
	bindkey -b N-end end-of-line

	bindkey -b N-pgup e_page_up
	bindkey -b N-pgdown e_page_down

(Note that on Win9x, you must set your console window to NOT be Auto
sized, and you must use the "settc" builtin to increase and then reduce
back the number of lines, in order to get a scrollbar. pgup and
pgdown will not work without a scroll bar)


To bind ctrl or alt combinations, use the following as examples.

	bindkey -b N-C-left backward-word
	bindkey -b N-M-right forward-word    

For Shift combinations:
	bindkey -b N-S-1 backward-word


e_dosify_next
-------------
A key bound to this editor function can be used to convert unix-style
paths to DOS-style paths.
For example,
	bindkey -b M-/ e_dosify_next
Then, if I had line like so:
	xcopy /e /u c:/nt40/system32
I would move the cursor to the C: and hit alt-/. magically, the command
line changes to
	xcopy /e /u c:\\nt40\\system32

This function converts every '/' to '\\' until the first space. If the
space is escaped by a '\', the function looks for the next space.

e_dosify_prev
-------------
Works like above, but on the previous word. Matt Landau pointed out that
this was much more convenient.

e_page_up
---------
Editor function to move console window up one page. Can be bound to
PageUp key.

e_page_down
----------
Ditto for page down.


Literal Prompt Characters
-------------------------
tcsh uses a special syntax for embedding literal character sequences in the
prompt. For example, ANSI escapes.
Thus, if you did
set prompt='%{<ESC>[44mfoo%}\>', 
this will print the prompt in the appropriate colors.

The color-ls patch in 6.07.09 implements parsing for ANSI escapes. To keep
the prompt specification consistent with the availablity of this feature,
the literal string will now accept ANSI escapes like color-ls would.

    set prompt='%{^[[1;34m%}%c03%{^[[0m%}\>'
	set prompt3='%{^[[1;31m%}Correct to %R ?(y|n|e)%{^[[0m%} '
#
#

ls-F is noticeably slow if color is set. This is especially true on slower
machines (P100, for example). You may not want to set it for those kinds
of systems. More so if you already have an external color-ls.

watch:
-----
Deprecated since Windows does not ship NETBIOS any more

Nice:
-----
//
// nice(niceness)
//
// where niceness is an integer in the range -6 to +7
//
// A usual foreground process starts at level 9 in the chart below
//
// the range -6 to +7 takes it from Base priority 15 down to 2. 
//
// Note that level 1 or > 15 are not allowed.
//
// Priority Level 11 (niceness -2) or greater affects system performance, 
//	so use with care.
//
// niceness defaults to  +4, which is lowest for background normal class.
// As in unix, +ve niceness indicates lower priorities.

/***************************************************************************
Niceness    Base    Priority class/thread priority

            1    Idle, normal, or high class,    THREAD_PRIORITY_IDLE

+7          2    Idle class,                     THREAD_PRIORITY_LOWEST
+6          3    Idle class,                     THREAD_PRIORITY_BELOW_NORMAL
+5          4    Idle class,                     THREAD_PRIORITY_NORMAL
+4          5    Background normal class,        THREAD_PRIORITY_LOWEST
                    Idle class,                  THREAD_PRIORITY_ABOVE_NORMAL
+3          6    Background normal class,        THREAD_PRIORITY_BELOW_NORMAL
                    Idle class,                  THREAD_PRIORITY_HIGHEST
+2          7    Foreground normal class,        THREAD_PRIORITY_LOWEST
                    Background normal class,     THREAD_PRIORITY_NORMAL
+1          8    Foreground normal class,        THREAD_PRIORITY_BELOW_NORMAL
                    Background normal class,     THREAD_PRIORITY_ABOVE_NORMAL
 0          9    Foreground normal class,        THREAD_PRIORITY_NORMAL
                    Background normal class,     THREAD_PRIORITY_HIGHEST
-1          10   Foreground normal class,        THREAD_PRIORITY_ABOVE_NORMAL
-2          11    High class,                    THREAD_PRIORITY_LOWEST
                    Foreground normal class,     THREAD_PRIORITY_HIGHEST
-3          12    High class,                    THREAD_PRIORITY_BELOW_NORMAL
-4          13    High class,                    THREAD_PRIORITY_NORMAL
-5          14    High class,                    THREAD_PRIORITY_ABOVE_NORMAL
-6          15    Idle, normal, or high class,   THREAD_PRIORITY_TIME_CRITICAL 
                  High class,                    THREAD_PRIORITY_HIGHEST


    16    Real-time class, THREAD_PRIORITY_IDLE
    22    Real-time class, THREAD_PRIORITY_LOWEST
    23    Real-time class, THREAD_PRIORITY_BELOW_NORMAL
    24    Real-time class, THREAD_PRIORITY_NORMAL
    25    Real-time class, THREAD_PRIORITY_ABOVE_NORMAL
    26    Real-time class, THREAD_PRIORITY_HIGHEST
    31    Real-time class, THREAD_PRIORITY_TIME_CRITICAL
****************************************************************************/

kill:
----

You can try to kill a process 4 ways:

kill -1 <pid> (which will send a sigint)
kill -2 <pid> (which will send a sigbreak)

1 and 2 are only good for processes started in the same console. The
signals cannot be sent to other process groups (other consoles/GUI apps).

kill -3 <pid> (which will send a quit message to each window of the child>

kill -7 <pid> , which will call TerminateProcess() 
