home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / s / csh.doc < prev    next >
Text File  |  1995-03-01  |  112KB  |  3,333 lines

  1.  
  2.         INSTRUCTIONS FOR C-SHELL VERSION: 5.40 (January 1995)
  3.         =====================================================
  4.  
  5.   Contents
  6.   --------
  7.  
  8.     O.    Installation
  9.     I.    Description
  10.     II.    Overview of major features
  11.     III.    Restrictions
  12.     IV.    Pipes
  13.     V.    Command Pre-processor
  14.     VI.    Command Line Editing
  15.     VII.    Function Keys
  16.     VIII.    Shell Commands
  17.     IX.    Special Set Variables
  18.     X.    Functions
  19.     XI.    Miscellaneous
  20.     XII.    Example source files
  21.     XIII.    Default values
  22.     XIV.    Object oriented features
  23.     XV.    Keymaps
  24.     XVI.    Scrolling
  25.  
  26.  
  27.  
  28. O.  Installation
  29. ----------------
  30.  
  31. This program requires at least AmigaOS 2.04 (KS37.175, WB37.67) or higher.
  32.  
  33. For  online  help  inside csh, assign CSH:  somewhere and put csh.doc there.
  34. Then  you can use the 'man' command for any desired command.  Press the HELP
  35. key for a command list.
  36.  
  37. You  can  simply  invoke  csh  from  the  command line or at the end of your
  38. startup-sequence,  because  csh is, from the AmigaDOS standpoint, not a true
  39. shell  like  l:shell-seg.   Nevertheless, csh is 'pure', so if your archiver
  40. forgot to set the 'p' bit, do it right now.
  41.  
  42. Proposed final setup:  If you want to make csh resident, do the following:
  43.  
  44.   1. Copy csh anywhere on your (hard)disk, e.g. dh1:tools
  45.   2. Make sure your s:startup-sequence contains:
  46.     resident dh1:tools/csh add
  47.     csh
  48.   4. In s:.login, put any commands to be called only once, like setmap,
  49.     assign, setclock. This is a shell script, use # for comments, and
  50.     don't use .key type commands.
  51.   5. In s:.cshrc, you put any commands that need to be executed on every
  52.     invocation, like 'alias', 'set' and so on.
  53.   6. Put the following to s:cli-startup and s:shell-startup, so csh will be
  54.     started in any window opened by NewCLI, NewShell or from workbench:
  55.         csh
  56.         endcli
  57.  
  58.  
  59. Additionally,  I  recommend  to assign CSH:  somewhere and put your docs and
  60. CShell scripts there.  You can do the assign from inside the shell, it's not
  61. needed at startup.
  62.  
  63. The file s:.cshrc is executed on every startup (of csh) if it exists,
  64. the file s:.login only on csh's first invocation after boot-time,
  65. the file s:.logout is executed on every termination (of csh).
  66.  
  67.  
  68.  
  69. I.  DESCRIPTION
  70. ---------------
  71.  
  72. This version of Shell is the successor of:
  73.     Shell V2.04 (C)Copyright 1986, Matthew Dillon, All Rights Reserved
  74.     Shell V2.04M-V2.07M by Steve Drew
  75.     Shell V2.08MI, V3.xxA and V4.xxA by Carlo Borreo & Cesare Dieni
  76.     Shell V5.xxL by U. Dominik Mueller
  77.     Shell V5.20+ by Andreas M. Kirchwitz
  78.  
  79.  
  80.  
  81. Responsible for the V5.20+ series of Cshell is:
  82.  
  83.      Andreas M. Kirchwitz
  84.      Seesener Str. 69, D-10709 Berlin, Germany
  85.      UUCP/InterNet: csh-fan@zikzak.in-berlin.de
  86.  
  87. Send wishes, detailed bug reports (and the beer bottles :) to the above
  88. address. I need your Csh version number and a reproducable bug generation
  89. example.
  90.  
  91. If you report Enforcer hits please send the complete Enforcer and SegTracker
  92. output. Otherwise it's of no earthly use.
  93.  
  94. The V5.20+ series is an ARP-free, OS-2.x-only pre-6.0 version of Cshell.
  95. It only has an english ascii-doc, but it sweetens the time until Csh 6.x
  96. (by Urban Mueller) is available ;-)
  97.  
  98.  
  99.  
  100. If you have any wishes, bug reports or beer bottles, send them to:
  101.  
  102.        FIDONET :  Urban Mueller@2:302/906 (AUGL)
  103.        INTERNET:  umueller@amiga.icu.net.ch
  104. or
  105.        U. Dominik Mueller
  106.        Schulhausstrasse 83
  107.     CH-6312 Steinhausen
  108.        SWITZERLAND
  109.  
  110. Any sign of intelligent life welcome! German, English and French spoken.
  111.  
  112. Please check the 'restrictions' chapter before reporting any bugs and add
  113. your CShell version and a description of your configuration.
  114.  
  115. You may distribute this program unmodified and for non-profit only.
  116.    *** YOU MAY NOT MODIFY THIS PROGRAM AND REDISTRIBUTE IT ***
  117. Please contact me if you want to make changes.
  118.  
  119.  
  120. AVAILABILITY
  121. ------------
  122.  
  123. CShell can always be downloaded at the AUGL BBS.  Some additionals parts
  124. (French documentation) are available there, too.
  125.  
  126. For those who want to get it per FIDO file request, the archive is always
  127. named like 'csh513.lzh' for CShell 5.13 and 'csh513s.lzh' for its source.
  128.  
  129. CShell is available via FTP from AmiNet (and mirrors) in the directory
  130. /pub/amiga/shell/ (the archive names are the same) and via UUCP/Internet-
  131. EMail from "mail-server@cs.tu-berlin.de" in the same directory.
  132.  
  133.  
  134. CREDITS
  135. -------
  136.  
  137. Arexx is a program by William Hawes.
  138. Cygnus Ed Professional (C) 1988 CygnusSoft Software.
  139.  
  140. Thanks to:
  141.  
  142. Matt Dillon, Steve Drew, Calro Borreo and Cesare Dieni for the previous
  143. versions of Csh.
  144.  
  145. Ralph Babel, Eddy Carroll, Gary Duncan, Randell Jesup, Steve Koren, Tim
  146. MacKenzie, Axel Roebel, Mike Schwartz for their code contributions and
  147. suggestions.
  148.  
  149. Michael Beer, Carl Johan Block, Hubert Feyere, Magnus Heldestad, Carsten
  150. Heyl, Alex Liu, Declan McArdle, Svante Eriksson, Luke Mewburn, Peter Orbaek,
  151. Allard Siemelink, Roddi Walker, Shimon Weissman and the unknown Swedish guy
  152. who found the double-LF bug for their bug reports and feedback.
  153.  
  154. Roy Haverman, Martin Horneffer, Hans-Christian Huerlimann, Daniel Pfulg,
  155. Patrizio Rusconi, Christian Schneider and especially Markus Illenseer for
  156. the German translation of the doc.
  157.  
  158. Olivier Berger for the French translation of the doc.
  159.  
  160.  
  161. AMIGAGUIDE
  162. ----------
  163.  
  164.   AmigaGuide, AmigaGuide.info, amigaguide.library, WDisplay, WDisplay.info
  165.        (c) Copyright 1992 Commodore-Amiga, Inc.  All Rights Reserved.
  166.           Reproduced and distributed under license from Commodore.
  167.  
  168.        AMIGAGUIDE SOFTWARE IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE;
  169.      NO WARRANTIES ARE MADE.  ALL USE IS AT YOUR OWN RISK.  NO LIABILITY
  170.                         OR RESPONSIBILITY IS ASSUMED.
  171.  
  172.  
  173. II. OVERVIEW
  174. ------------
  175.  
  176. Shell provides a convenient AmigaDos alternative command interface.  All its
  177. commands  are internal and thus it does not rely on the c:  commands for any
  178. functionality.
  179.  
  180. Major features include:
  181.     - freely programmable command line editing
  182.     - simple history
  183.     - piping
  184.     - aliases with arguments
  185.     - variables & variable handling (embedded variables)
  186.     - file name expansion via wild carding ('?', '*' and more)
  187.     - conditionals (if/else etc..)
  188.     - source files  (w/ gotos and labels)
  189.     - tab file name completion
  190.     - object oriented features (file classes, actions)
  191.     - many built in commands to speed things up
  192.     - full functionality on VT terminals
  193.  
  194. CShell runs on minimum stack, for recursive aliases and source files better
  195. increase stack to 10K or more.
  196.  
  197. If you use CShell for the first time, remember the following:
  198.     - CShell internal commands must be lowercase & can be abbreviated
  199.     - AmigaDOS command 'Execute' causes some trouble. You cannot
  200.       redirect it, you must not rename it, and you get no return code.
  201.       You can also use 'source' to start your scripts, but you'll have
  202.       to rewrite them a bit. Besides the '.key'-type commands, 'source'
  203.       is downward compatible with 'Execute'.
  204.     - You can always get more information on a command if csh.doc is
  205.       in the current directory or in csh: (you will be able to modify
  206.       this) and you enter 'man <command>'
  207.     - The wild card #? doesn't work. Use *
  208.        (#? only works if you "escape" it... better use * :-)
  209.  
  210.  
  211. III. RESTRICTIONS
  212. -----------------
  213.  
  214. The c:Execute command cannot be redirected, does not return error codes, and
  215. might cause other problems. It will not work at all if it has been renamed.
  216.  
  217. The  VDK: handler and Frank Seidel's BootRam-Handler have a bug with setting
  218. file  dates,  so  when  using  the copy command you should try the -d and -p
  219. switches, otherwise your file date will be bad. (This is not a shell bug)
  220.  
  221. If  using  it with conman you may consider starting shell with the -a switch
  222. to  turn  off  shell's  command line editing and use conmans instead. You'll
  223. lose, however, many shell features like file name completion.
  224.  
  225. CB-handler  (a tool that installs a scrollbar in the CLI window) is not 100%
  226. compatible  with  cshell.  The log will not always represent the real screen
  227. contents.
  228.  
  229. Don't  use  the  "Iconify" feature of KingCON (a CON-Handler replacement that
  230. gives  you  scrollbar  and  other  features in CLI windows). Don't ignore the
  231. warning,  KingCON  gives you when iconifying a Cshell window. This will crash
  232. your  system  because Iconify makes Cshell's internal window pointer invalid.
  233. Start Cshell with option "-a" or "-t" to use "Iconify" safely.
  234.  
  235.  
  236. IV. NOTES ON PIPES
  237. ------------------
  238.  
  239.     PIPES
  240.     PIPES  have  been implemented using temporary T:  files.  Thus, you
  241.     should be  careful  when  specifying  a 't:*' expansion as it might
  242.     include the temporary files. These files are deleted on completion
  243.     of the pipe segment.
  244.  
  245.     The file names used are completely unique, even with multiple shell
  246.     running simultaneously.
  247.  
  248.     My  favorite  new  feature is the fact that you can now redirect to
  249.     and  from,  and pipe internal commands.  'echo charlie >ram:x', for
  250.     instance.  Another favorite:
  251.  
  252.     echo "echo mem | csh" | csh
  253.  
  254.     No BCPL program should be output-append redirected (>>).
  255.  
  256.  
  257. V.  COMMAND PRE-PROCESSOR
  258. -------------------------
  259.  
  260.     PREPROCESSING
  261.     Preprocessing is done on the command line before it is passed on to
  262.     an internal or external routine:
  263.  
  264.     ^c    where c is a character is converted to that control
  265.         character. Thus, say '^l' for control-l.
  266.  
  267.     \233    insert character code 233 octal. Do not use values between
  268.         200o and 232o, as they have special meanings. \240 is the
  269.         word separator.
  270.  
  271.     $name    where name is a variable name. Variable names can consist
  272.         of 0-9, a-z, A-Z, and underscore (_).  The contents of the
  273.         specified variable is used.  If the shell variable doesn't
  274.         exist, csh tries to find a local or global (ENV:) variable
  275.         of the same name. If that fails, too, "$name" is inserted.
  276.         That is, if the variable 'i' contains 'charlie',
  277.         then '$i' -> 'charlie'.
  278.         If the variable 'i' doesn't exist, then '$i' -> '$i'.
  279.  
  280.     ;    delimits commands.   echo charlie ; echo ben.
  281.  
  282.     ' '    (a space). Spaces delimit arguments.
  283.  
  284.     "string" a quoted string. Trailing quotes are optional.
  285.         For instance, if you want to echo five spaces and an 'a':
  286.  
  287.         echo      a       -> a
  288.         echo "    a"      ->      a
  289.  
  290.         See also builtin variable "_cquote".
  291.  
  292.     \c    override the meaning of special characters.
  293.         '\^a' is a circumflex and an a rather than control-a.
  294.         To get a backslash, you must say '\\'.
  295.  
  296.         also used to overide alias searching for commands.
  297.  
  298.     >file    specify output redirection.  All output from the command is
  299.         placed in the specified file.
  300.  
  301.     >>file    specify append redirection
  302.         (Does not work with BCPL programs).
  303.  
  304.     <file    specify input redirection. The command takes input from the
  305.         file rather than the keyboard (note: not all commands
  306.         require input; it makes no sense to say 'echo <charlie'
  307.         since the 'echo' command only outputs its arguments).
  308.  
  309.     <>file    specify input AND output redirection. The file must be
  310.         either "NIL:" or an interactive stream (eg, a console
  311.         window: <>CON:////InOut).
  312.  
  313.     |    PIPE specifier.  The output from the command on the left
  314.         becomes the input to the command on the right.  The current
  315.         SHELL implementation uses temporary files to store the data.
  316.  
  317.     !!    execute the previously executed command.
  318.     !nn    (nn is a number).  Insert the history command numbered n
  319.         (see the HISTORY command)
  320.     !partial search backwards through the history list for a command
  321.         which looks the same as 'partial', and execute it.
  322.  
  323.     #    enter comment.  The rest of the line is discarded.
  324.         (note: \# will, of course, overide the comment character's
  325.                special meaning)
  326.  
  327.     {e hi;e ho} executes two commands as one, so they can be redirected
  328.         together (see ALIAS command). The trailing curly brace is
  329.         optional.
  330.  
  331.     $(foo)    insert the stdout of the command 'foo' at this position of
  332.         the command line. Every line of the output will count as one
  333.         argument. The closing parenthesis is optional.
  334.  
  335.     `foo`    insert the stdout of the command 'foo' at this position of
  336.         the command line. Every blank separated word will count as
  337.         one argument. Leading, trailing and multiple blanks will be
  338.         removed. The trailing backtick is optional.
  339.  
  340.     $nn    (nn is a number).  Cshell scripts only!
  341.         Insert argument number nn for $nn.  Thus, $1 becomes the
  342.         first argument, $2 the second, $3 the third and so on.
  343.         $0 is the name of the command (script).  If there's no
  344.         argument nn then $nn remains unchanged (unset variable).
  345.  
  346.     $#    Number of arguments.  Cshell scripts only!
  347.         For example: if $# is 3 then $3 will be the highest
  348.         meaningful variable for an argument.
  349.  
  350.     --    stop option parsing here. Works for internal commands only.
  351.         Example: rm -- -x will remove the file '-x'
  352.  
  353.     Please note the subtle differences between
  354.         alias count {echo one;echo two}
  355.         alias count "echo one;echo two
  356.     The first form will create an alias that contains a local alias. The
  357.     other will create a plain alias. Also, things within braces will not
  358.     be parsed more than once, therefore a backslash needs not be pre-
  359.     ceded by a pair of backslashes. Thus the commands look the same as
  360.     if they were to be typed in at the prompt. To echo lots of '#',
  361.     either use:
  362.         forever {echo \#
  363.         forever "echo \\\#
  364.     A block can spread over several lines. Refer to the SOURCE command.
  365.  
  366.  
  367. VI. COMMAND LINE EDITING
  368. ------------------------
  369.  
  370.     o The command line can be up to 255 chars.
  371.     o Inserts  and  deletes  are handled correctly over multiple lines.
  372.     o The script 'menu.sh' installs an intuition menu that contains most
  373.       editing functions
  374.  
  375.     EDITING
  376.  
  377.     -- MOVING --
  378.     Left Arrow      One character left
  379.     Right Arrow      One character right
  380.     Shift-Left Arrow  One word left
  381.     Shift-Right Arrow One word right
  382.     ESC-Left Arrow      Beginning of line (^A) (^Z)
  383.     ESC-Right Arrow      End of line       (^E)
  384.     -- DELETING --
  385.     Backspace      Previous character
  386.     Del          Character under cursor
  387.     ESC-Backspace      Previous word     (^W)
  388.     ESC-Del          Next word
  389.     ESC-x-Backspace      To start of line  (^B)
  390.     ESC-x-Del      To end of line    (^K)
  391.     ESC-d          Entire line       (^X)
  392.     -- HISTORY --
  393.     Up Arrow      Recall previous commands
  394.     Down Arrow      Recall commands
  395.     Shift-Up Arow      Get history from partial (or number)
  396.     Shift-Down Arrow  Go below last command of history
  397.     ESC-Up Arrow      Get start of history
  398.     ESC-Down Arrow      Get end of history
  399.     ESC-!          Get history from partial (or number)
  400.     ^T          Insert tail (all but first word) of previous line
  401.     ^P          Duplicate previous word (useful for mv)
  402.     -- COMPLETION --
  403.     TAB          Inserts first matching file name
  404.     Shift-TAB      Inserts longest common substring
  405.     ESC-TAB          Inserts all matching file names (also ESC-*)
  406.     ESC-c          Does a quick cd on left word (TAB for cycling)
  407.     ESC-~          Inserts the last current directory
  408.     ^D          Shows all files that match a pattern (also ESC-=)
  409.     ESC-p          Insert first/next matching program name
  410.     ESC-P          Shows all matching program names
  411.     -- EXECUTING LINE --
  412.     Return          Executes line
  413.     ESC-Return      Executes this line of history & brings up next one
  414.     ^N          Next line. Don't exec this one but store history
  415.     ^\          EOF (directly exits)
  416.     -- MISCELLANEOUS --
  417.     ^L          Retype current line.
  418.     ^O          Echo a ^O
  419.     ^R          Repeat last command (don't play with this)
  420.     ^U          Undo/Redo last edit
  421.     ^V          Quote next char
  422.     ESC-i          Toggle Insert/Overwrite
  423.     f1-f10          Execute command if variable exists.
  424.     F1-F10          More commands (Shifted f keys).
  425.     Help          Invokes help command
  426.  
  427. Whenever  the  cursor is placed on or directly after an incomplete file name
  428. and   you   press  TAB,  CShell  inserts  for  the  first  filename  (sorted
  429. alphabetically) that matches the name part already typed.  Any wildcards are
  430. allowed  here, if none are given, '*' is appended.  Immediately pressing TAB
  431. again  brings  up  the next file name that matched the substring.  Shift-TAB
  432. will  only  insert  the  as much as is common to all files that matched your
  433. abbreviation.  If pressed again, behaves just like TAB.  ESC-Tab inserts the
  434. name  of the directory where you would have ended up with a quick cd to that
  435. substring.
  436.  
  437. Note that ^D now means 'quit batchfile' like under AmigaDOS and is no longer
  438. used for quitting CShell.  If you want it back, enter 'keymap 0 4=41'
  439.  
  440. The  CTRL  keys  FGVY  are unset, feel free to map them to any function (see
  441. chapter XV).  You can also remap all preset keys.
  442.  
  443. VII. FUNCTION KEYS
  444. ------------------
  445.  
  446.     FUNKEY
  447.     Function keys now insert text to the current position on the command
  448.     line. They may be terminated with a ^M (return). f1 would be non-
  449.     shifted where as F1 is shifted.
  450.     Most of functions key have a default definition, but it may be
  451.     changed.
  452.  
  453.         $ set f1 dir df0:^M
  454.  
  455.     will add the text 'dir df0:<return>' to the current line.
  456.  
  457.         $ set f1 dir
  458.  
  459.     would only add 'dir' you could then enter ' df0:<return>'
  460.  
  461.  
  462. VIII. SHELL COMMANDS
  463. --------------------
  464.  
  465.     STARTUP OPTIONS
  466.     First to start shell from a CLI:
  467.  
  468.     csh [-abcCfiknstv] [-c command;command]
  469.     csh [-abcCfiknstv] [batchfile1 ... batchfileN]
  470.  
  471.      -a  AUX: mode. No command line editing and text highlighting
  472.           (window opening is not forced and AUTO-windows don't lose
  473.            the ability to be closed)
  474.      -b  starts shell in background, which means only task priority -1.
  475.      -c  allows execution of one command line and then exits out
  476.          of  shell.   This  is  useful for running an internal shell
  477.          commands in the background or from an external application:
  478.         run csh -c "dir df0:; copy -r df0: df1: >nil:; echo Done"
  479.      -C  same as -c, but the command line is not parsed twice. This
  480.          allows passing of file names with blanks within.
  481.         run csh -C rm "Ram Disk:tempfile"
  482.      -f  starts shell in foreground, which means only task priority 1.
  483.          you might reset this prioritiy to 0 at the end of your .login
  484.      -k  sets _nobreak before doing anything
  485.      -L  suppresses starting of s:.logout
  486.      -m  sets _nomatch  (which is unset by default)
  487.      -M  don't clear menus (especially for KingCON),
  488.          by default CSH clears menus of its window
  489.      -n  suppresses starting of s:.login
  490.      -N  suppresses starting of s:.cshrc
  491.      -s  globally enables the asterisk * as alias for #? in AmigaDOS 2.0
  492.          This means you can use * inside file requesters as well.
  493.          (obsolete option -- * is default -- #? is still allowed !!)
  494.      -t  terminal mode. You can use command line editing and text high-
  495.          lighting on a VT100 compatible terminal. To swap backspace
  496.          and DEL, refer to the 'keymap' command
  497.           (window opening is not forced and AUTO-windows don't lose
  498.            the ability to be closed)
  499.      -v  sets _verbose to 'hs' before doing anything.
  500.      -V  send only VT100 compatible control sequences
  501.           (no special Amiga control sequences)
  502.      -w  don't fetch pointer of window Cshell is running in,
  503.           eg, for running Cshell remote or with KingCON (iconify)
  504.           (menus, titlebar and some window related commands disabled)
  505.  
  506.     COMMAND EXECUTION
  507.  
  508.     Internal shell commands are case sensitive and may be abbreviated.
  509.     Also commands buffered with "rehash" may be abbreviated. This can
  510.     be toggled with the variable "_abbrev".
  511.  
  512.    The first argument is the command-name... here is (in order) how Shell
  513.    tries to execute it:
  514.  
  515.     1)  The alias list is searched for an alias with an exactly
  516.         matching name.
  517.     2)  Internal commands list is scanned for a command even partially
  518.         matching name (so you can, for instance, say resi for resident;
  519.         however, you should specify enough of a command to be unique).
  520.     3)  Then, the list of functions is scanned for a command that
  521.         matches completely. If one is found, the result of the function
  522.         is echoed to stdout.
  523.     4)  Now the command is assumed to be external.
  524.         Arguments with blanks, semicolons or empty strings will be
  525.         surrounded by quotes.
  526.     5)  If the file is a directory, a 'cd <file>' will be performed to
  527.         it.
  528.     6)  AmigaDOS resident list are scanned for it (you can use Shell's
  529.         'resident' command to add/remove a file in the DOS list).
  530.     7)  If the file is in the current directory and it's executable, it
  531.         is started.
  532.     8)  Then it is searched in the AmigaDOS path and c:
  533.     9)  Now, the shell path ($_path) is searched. If it's found and
  534.         executable, it's started. If it has the 's' bit set, it will
  535.         be executed using the appropriate shell. See FOREIGN SHELLS
  536.     10) If there exists a file with the suffix '.sh' and the same root
  537.         in the current directory or in the shell path, it is 'source'd.
  538.     11) Then the variable _rxpath is examined. If there exists a file
  539.         with the suffix '.rexx' and the same root in the current direc-
  540.         tory or in '$_rxpath', 'RX <file>' will be performed.
  541.     12) If all failed, an 'exec' action is sent to the file. See chapter
  542.         XIV for more info on classes and actions.
  543.  
  544.     To enforce that the external 'dir'-command is used, enter 'Dir'. It
  545.     is a good habit to uppercase the first letter of all external com-
  546.     mands, even if this is not necessary.
  547.  
  548.     AUTOMATIC SOURCING may be accomplished by naming shell scripts with
  549.     a .sh suffix.  Thus, if you say 'stuff' and the file 'stuff.sh'
  550.     exists in your current or anywhere in Shell search path (NOTE:
  551.     won't be found in the AmigaDOS path), it will be SOURCED with all
  552.     arguments you have given placed in the $_passed variable.  This is
  553.     equivalent to typing 'source stuff.sh'
  554.  
  555.     FOREIGN SHELLS are supported through key characters at the beginning
  556.     of their scripts.  If a file in the command search path has the s-bit
  557.     set, the first few bytes are read. If the first two are either '#!'
  558.     or ';!', the rest of the first line will be interpreted as the name
  559.     of the shell that is supposed to execute the script.
  560.     If they are '/*', the command 'RX' is used, if none of the above,
  561.     'c:Execute'. Example:
  562.       #!SKsh -c source
  563.  
  564.     WILDCARDS
  565.     Most shell commands will accept multiple arguments that can
  566.     be as a result of wild card expansion.  Also when calling
  567.     an external command shell will first expand any wild cards
  568.     to separate arguments.  If you wish to have the external command
  569.     handle it's own wild carding you will need to insert quotes
  570.     around the special wild card characters or use an alias (see
  571.     explanation of 'alias')
  572.  
  573.     eg.
  574.         arc a new.arc *.txt    - shell will expand and pass to arc
  575.         arc a new.arc "*.txt"    - let arc expand the wild cards.
  576.         alias arc "*a Arc $a"    - now shell will never expand
  577.  
  578.     The patterns are fairly extensive, and approximate some of the
  579.     ability of Unix/grep "regular expression" patterns.  Here are the
  580.     available tokens:
  581.  
  582.     ?    Matches a single character.
  583.     #    Matches the following expression 0 or more times.
  584.     (ab|cd)    Matches any one of the items seperated by '|'.
  585.     ~    Negates the following expression.  It matches all strings
  586.         that do not match the expression (aka ~(foo) matches all
  587.         strings that are not exactly "foo").
  588.     [abc]    Character class: matches any of the characters in the class.
  589.     [~bc]    Character class: matches any of the characters not in the
  590.         class.
  591.     a-z    Character range (only within character classes).
  592.     %    Matches 0 characters always (useful in "(foo|bar|%)").
  593.     *    Synonym for "#?", not available by default in 2.0. Available
  594.         as an option that can be turned on.
  595.  
  596.     "Expression" in the above table means either a single character
  597.     (ex: "#?"), or an alternation (ex: "#(ab|cd|ef)"), or a character
  598.     class (ex: "#[a-zA-Z]").
  599.  
  600.     Additional wildcards allowed:
  601.  
  602.     .../*    recursive search down ALL sub directories from current level
  603.     !    synonym for ~, supported for compatibility
  604.     &    prefixed to patterns, ask confirmation for each file
  605.     ~    the previous current directory (if separated)
  606.     Note that a pattern must contain a '?' or a '*', otherwise the other
  607.     special characters are not recognized. Furthermore, you cannot spe-
  608.     cify a single '?' as a pattern in the first argument to a command,
  609.     as this will be passed on to the command in order to show its usage.
  610.  
  611.     If pattern.library is present it LIBS:, it will be used for the
  612.     matching. (disabled, now Cshell always uses dos.library)
  613.  
  614.     Examples:
  615.  
  616.     df0:.../*    all files in all directories on df0:
  617.     df0:.../!*.info    full directory tree of df0: but exclude
  618.             any ugly .info files.
  619.     !*.o !*.c    will result in ALL files matching since what
  620.             doesn't match the !*.o will match the !*.c
  621.     df1:&*        all files in root of df1:, but ask
  622.             confirmation for each
  623.     *.[co]        all files ending in .c or .o
  624.     ~*.[co]        all files NOT ending in .c nor in .o
  625.     ~        the previous current directory
  626.     ~/*.c        all .c files in the previous current directory
  627.     ~//        the parent of the previous current directory
  628.     .        the current directory
  629.     ./foo.c        the same as foo.c
  630.     ..        the parent of the current directory
  631.     ../foo.c    the file foo.c in the parent directory
  632.  
  633.     Note that some commands prevent wild card expansion. These are:
  634.       - dir, rpn, whereis, window
  635.     Those commands will expand the wild cards themselves. This is why
  636.       dir @without( *.? , *.o )
  637.     will not work. Instead use:
  638.       set arg @without( *.? , *.o );dir $arg
  639.  
  640.     There is one exception to the rules given above: A single '?' as
  641.     the first argument will *not* expand in order to allow you to get
  642.     the usage of CLI and csh commands easily.
  643.  
  644.     Due to implementation limitations, patterns are only recognized
  645.     if they contain *, ?, [ or ]. To let Cshell expand patterns which
  646.     does not contain one of these chars just append "[]" to the
  647.     pattern (this will NOT change the meaning of the pattern!)
  648.  
  649.  
  650. LIST OF COMMANDS:
  651. -----------------
  652.  
  653.     ABORTLINE
  654.  
  655.     Usage    : abortline
  656.     Example    : echo a;abort;echo b
  657.     Results    : a
  658.  
  659.     Causes the rest of the line to be aborted. Intended for use in
  660.     conjunction with exception handling.
  661.  
  662.     ACTION
  663.  
  664.     Usage    : action [-a] actionname file [arguments]
  665.     Example : action extr csh515.lzh csh.doc
  666.  
  667.     Sends an action to a file. See chapter XIV CLASSES
  668.  
  669.     Options:
  670.      -a (abort) returns 0 if failed and 1 if successful. Otherwise,
  671.                 normal error codes (10 or 11) are returned
  672.  
  673.     ADDBUFFERS
  674.  
  675.     Usage    : addbuffers drive
  676.           addbuffers drive buffers [drive buffers ...]
  677.     Example    : addbuffers df0: 24
  678.  
  679.     Just like AmigaDOS addbuffers command, causes new buffers to be
  680.     allocated for disk I/O.  Each buffer costs 512 bytes of memory,
  681.     CHIP memory if a disk drive. Buffers may be negative (to remove
  682.     buffers from a drive).
  683.  
  684.     To show actual amount of buffers use "addbuffers drive"
  685.     or "addbuffers drive 0".
  686.  
  687.     ADDPART (or TACKON)
  688.  
  689.     Equivalent to TACKON.
  690.  
  691.     ALIAS
  692.  
  693.     Usage    : alias [name [command string] ]
  694.     Example    : alias vt "echo Starting VT100;run sys:tools/vt100"
  695.  
  696.     Sets a name to be a string. You can alias a single name to a set
  697.     of commands if you enclose them in quotes as above. By simply
  698.     typing vt, the command line above would be executed.
  699.  
  700.     Aliases may call each other, but direct recursion is prohibited,
  701.     so the following works: alias ls "ls -s"
  702.     To prevent alias replacement, enter: \ls
  703.  
  704.     If you run aliases into background, they will be recursively
  705.     resolved. This may result in endless loops, if the name of the
  706.     alias and the command it runs are equal. Use absolute pathes or
  707.     mix the case of the command to avoid recursion.
  708.  
  709.     By typing "alias name", you will get the alias for that name, while
  710.     with "alias" you get a list of all alias.
  711.  
  712.     ARGUMENT PASSING TO AN ALIAS:
  713.  
  714.     Usage    : alias name "%var[%var...] [ command_string ]"
  715.           alias name "*var[%var...] [ command_string ]"
  716.     Example    : alias xx "%q%w echo hi $q, you look $w
  717.           xx Steve great today
  718.     Results    : hi Steve, you look great today
  719.  
  720.     The second form of the alias command allows passing of arguments
  721.     to any position within the command string via use of a variable
  722.     name. To pass arguments to the end of a command string this method
  723.     is actually not necessary. These variables are local, so they don't
  724.     destroy another variable with the same name.
  725.     If you specify multiple arguments, every argument will be assigned
  726.     one word, and the last argument will be assigned the rest of the
  727.     command line.
  728.  
  729.     Using a '*' instead of the first '%' prevents wild card expansion:
  730.         alias zoo "*a zoo $a
  731.     To expand the wild cards after you got them, use
  732.         exec set a $a
  733.  
  734.     IMPLICIT ALIASES:
  735.  
  736.     Usage    : {command;command}
  737.           {%var command;command} arg arg
  738.     Example    : {%tmp echo $tmp $tmp} hello    --> hello hello
  739.  
  740.     Curly braces define temporary aliases. They can be redirected as
  741.     a whole, can have arguments and local variables. They count as
  742.     one argument, even if there are blanks inside (as with quotes), and
  743.     they may be nested. Complex alias definitions can use the braces
  744.     instead of quotes, although this will add some calling overhead.
  745.     The closing curly brace is optional if at the end of line.
  746.     Example:
  747.  
  748.     alias assert {e "Are you sure? ";input -s sure
  749.  
  750.     ASCII
  751.  
  752.     Usage    : ascii [-ho]
  753.           ascii [-ho] string
  754.  
  755.     If called without arguments, ascii outputs a complete ASCII table.
  756.     Given a string, shows each character in ASCII.
  757.  
  758.     Options:
  759.      -h shows numbers in hexadecimal
  760.      -o shows numbers in octal
  761.  
  762.     ASSIGN
  763.  
  764.     Usage    : assign
  765.           assign logical
  766.           assign [-adlnp] logical1 physical1 [log2 phy2 ... ]
  767.  
  768.     The first form shows all assigns.
  769.     The second form kills one assign.
  770.     The third form assigns logical1 to physical1 and so on.
  771.  
  772.     Options:
  773.      -a adds a new path to an existing assign
  774.      -d creates a deferred (late-binding) assign
  775.          (identical with old option -l)
  776.      -p creates a path (non-binding) assign
  777.          (identical with old option -n)
  778.  
  779.     For definition of add/defer/path, refer to your AmigaDOS manual.
  780.  
  781.     BASENAME
  782.  
  783.     Usage    : basename var path [path ...]
  784.     Example    : basename x df0:c/Dir    # sets x to "Dir"
  785.  
  786.     Sets var specified to basenames of paths.
  787.  
  788.     CAT (or TYPE)
  789.  
  790.     Usage    : cat [-n] [file file....]
  791.     Example    : cat foo.txt
  792.  
  793.     Type the specified files onto the screen.  If no file is specified,
  794.     STDIN in used (note: ^\ is EOF).  CAT is meant to output text files
  795.     only. 
  796.  
  797.     Options:
  798.       -n  output numbered lines.
  799.  
  800.     CD
  801.  
  802.     Usage    : cd [path]
  803.           cd -g device1 [device2 [device3 ...]]
  804.  
  805.  
  806.     Options:
  807.      -g generate a list of all directories on the given devices.
  808.  
  809.     Change your current working directory.  You may specify '..' to go
  810.     back one directory (this is a CD specific feature, and does not
  811.     work with normal path specifications).
  812.  
  813.     In most cases, you won't have to use the CD command. Just type
  814.     the desired directory at the prompt (very handy in conjunction with
  815.     file name completion). Typing a ~ alone on a command line cd's
  816.     to previous current directory.
  817.  
  818.     There are two situations left when you still need it:
  819.  
  820.     Entering 'cd *tem' will cd to the first name matched.
  821.  
  822.     The second form generates a list (an ASCII file) of all direc-
  823.     tories on the given devices. It will be stored in the file given
  824.     in $_qcd (default: 'csh:csh-qcd'). Note that this ASCII file will
  825.     not be merged but overwritten. Once you have generated this file,
  826.     you can cd to any directory on your harddisk(s) even if it's not
  827.     in the current directory.
  828.     If you have two directories of the same name and you use one of
  829.     them more, move the more important one to the beginning of the
  830.     qcd file. You might also sort the file.
  831.     It is legal to type just an abbreviation of the directory name
  832.     you want to cd to. No asterisk '*' necessary. If you end up in
  833.     the wrong directory, cd to the same directory again (best done
  834.     by Cursor-Up + RETURN). You will cycle through all directories
  835.     that matched the given abbreviation. The other possibility is to
  836.     specify the full name of the parent directory: cd devs/keym
  837.     You may also add devices and assigns, so if 'PageStream:' is one
  838.     line in the qcd-file, a cd to 'page' is successful.
  839.  
  840.     CD without any arguments displays the path of the directory you
  841.     are currently in.
  842.  
  843.     CHGRP
  844.  
  845.     Usage    : chgrp group file1 ... filen
  846.     Example    : chgrp 42 myfile
  847.  
  848.     Set group-id (0-65535) or group-name of specified files.
  849.     (currently, name-to-id mapping is not implemented)
  850.  
  851.     CHMOD
  852.  
  853.     Usage    : chmod [u|g|o|a][+|-|=][flags] file1 ... filen
  854.     Example    : chmod u+rwe myfile
  855.  
  856.     Set AmigaDOS file protection flags for the file specified.
  857.     Valid flags are h, s, p, a, r, w, e, d.  (x is the same as e)
  858.  
  859.     Ownership:
  860.       u  Set specified bits for User (aka Owner)
  861.       g  Set specified bits for Group
  862.       o  Set specified bits for Other (not User, not Group)
  863.       a  all, alias for "ugo" (User/Group/Other)
  864.     Specifying no ownership is equal to 'u'.
  865.  
  866.     Modes:
  867.       +  Set specified bits, leave all others
  868.       -  Clear specified bits, leave all others
  869.       =  Set specified bits, clear all others
  870.     Specifying no mode is equal to '='.
  871.  
  872.     Archive bit cleared by default!
  873.  
  874.     Note: This command is equivalent to "protect" except that the
  875.           arguments for filename(s) and flag(s) are reversed.
  876.  
  877.     CHOWN
  878.  
  879.     Usage    : chown owner file1 ... filen
  880.     Example    : chown 42 myfile
  881.  
  882.     Set owner-id (0-65535) or owner-name of specified files.
  883.     (currently, name-to-id mapping is not implemented)
  884.  
  885.     CLASS
  886.  
  887.     Usage    : [-n] name {type=param} [ "actions" {action=command} ]
  888.     Example : class zoo offs=20,dca7c4fd ext=.zoo actions view="zoo l"
  889.  
  890.     Defines a new class of files and the actions to be taken on them
  891.     in various cases, or shows old definitions if given no arguments.
  892.     See section XIV: OBJECTS
  893.  
  894.     Options:
  895.       -n (new)  forgets old definitions
  896.  
  897.  
  898.     CLOSE
  899.  
  900.     Usage    : close [filenumber]
  901.  
  902.     Close the specified file opened by open. Without filenumber, closes
  903.     all open files. See open and flist for more info.
  904.  
  905.     CLS
  906.  
  907.     Usage    : cls
  908.  
  909.     This is an alias. It only clears the screen, but also works on a
  910.     terminal (echo ^L doesn't).
  911.  
  912.     COPY (or CP)
  913.  
  914.     Usage    : copy [-udfpmo]  file file
  915.     or    : copy [-udfpmo]  file1 file2...fileN dir
  916.     or    : copy [-rudfpo] dir1...dirN file1...fileN dir
  917.  
  918.     Options    :
  919.      -r recursive, copy all subdirectories as well.
  920.      -u update, if newer version exists on dest, don't copy
  921.      -f freshen, if file doesn't exist on dest or newer, don't copy
  922.      -q suppresses 'not newer' and 'not there' messages in -u and -f
  923.      -d don't set destination file date to that of source.
  924.      -p don't set destination protection bits to those of source.
  925.      -m erases the original. does not work with -r
  926.      -o overwrites write/delete-protected, reads read-protected
  927.      -a don't clear archive bit
  928.  
  929.     Example    : copy -r df0: df1:
  930.  
  931.     Copy files or directories. When copying directories, the -r option
  932.     must be specified to copy subdirectories as well.  Otherwise, only
  933.     top level files in the source directory are copied.
  934.  
  935.     All files will be displayed as they are copied and directory's
  936.     displayed as they are created. This output can be suppressed by
  937.     redirecting to nil: eg. copy -r >nil: df0: df1:
  938.  
  939.     Copy will abort after current file on Control-C.
  940.  
  941.     Copy by default sets the date of the destination file to that of
  942.     the source file. To overide this feature use the -d switch.
  943.  
  944.     Similarly, it sets protection bits (flags) to those of source and
  945.     any file comment will be copied. To avoid this use -p. The archive
  946.     bit is always cleared by default (use option -a to leave it
  947.     untouched).
  948.  
  949.     Another useful option is the -u (update) mode where copy will not
  950.     copy any files which exists already in the destination directory
  951.     if the destination file is newer or equal to the source file.
  952.     This is useful when developing code say in ram: eg. 'copy *.c ram:'
  953.     when done you can copy -u ram: df1: and only those modules you have
  954.     modified will be copied back.
  955.  
  956.     Copy command will now create the destination directory if it does
  957.     not exist when specified as 'copy [-r] dir dir'. If you specify
  958.     copy file file file dir, then 'dir' must already exist.
  959.  
  960.     CP (or COPY)
  961.  
  962.     Equivalent to COPY.
  963.  
  964.     DATE
  965.  
  966.     Usage    : date [-bsr] [new date and/or time]
  967.     Example    : date Wednesday  # this refers to NEXT wed, of course
  968.  
  969.     Options:
  970.       -b print date/time from the battery clock, if existent
  971.       -s stores the current time internally
  972.       -r shows time relative to last stored in secs and hundredths
  973.  
  974.     Used to read or set system date and/or time. All standard options
  975.     may be used (yesterday, tomorrow, monday, etc.).
  976.     Leading zero's are not necessary.
  977.     Without parameters shows Dddddd DD-MMM-YY HH:MM:SS.
  978.  
  979.     DEC
  980.  
  981.     Usage    : dec varname [value]
  982.     Example    : dec abc
  983.  
  984.     Decrement the numerical equivalent of the variable with specified
  985.     value (default: 1) and place the ASCII-string result back into
  986.     that variable.
  987.  
  988.     DELETE (or RM)
  989.  
  990.     Usage    : delete [-fpqrv] file file file...
  991.     Example    : delete foo.txt test.c
  992.  
  993.     Remove (delete) the specified files.  Remove always returns
  994.     errorcode 0.  You can remove empty directories.  
  995.  
  996.     Options:
  997.      -r recursively remove non-empty directories.
  998.      -p (or f); remove delete-protected files.
  999.      -v toggle verbose output.  Useful if 'delete' is aliased.
  1000.      -q (quit), delete aborts if the file to be removed didn't exist
  1001.          or couldn't be deleted. This does _not_ affect non-matching
  1002.          wildcards.
  1003.  
  1004.     If you specify any wildcard deletes the files will be listed as
  1005.     they are deleted. This can be suppressed by redirecting to nil:
  1006.  
  1007.     DIR (or LS)
  1008.  
  1009.     Usage    : dir [-abcdfhiklnoqstuv] [-z [lformat]] [path path ... ]
  1010.     Example    : dir -ts downloads:
  1011.           dir -lz "%7s %-.16n %m" *.c
  1012.     Options:
  1013.      -d list directories only
  1014.      -f list files only
  1015.      -h list only files which not start with a dot, end with '.info' or
  1016.         have the h-flag set. Adds an 'i' bit to the flags which tells
  1017.         if an according .info file exists.
  1018.      -s short multi(4) column display.
  1019.      -c don't change colors for directories
  1020.      -q quiet display. does not show length in blocks
  1021.      -o display file nOtes
  1022.      -n display names only
  1023.      -p display full path names and suppress directory titles
  1024.      -a shows the age of all files in the format  days hours:minutes
  1025.      -i identifies every file, shows the type instead of the date.
  1026.         See chapter XIV CLASSES
  1027.      -v (viewdir) recursively sums up lengths of the files in a dir
  1028.      -l sorts the files by their length, longest first.
  1029.      -t sorts the files by their time, most recent first.
  1030.      -k sorts the files by their class (klass)
  1031.      -b sorts the files backwards.
  1032.      -g prints directories at the beGinning
  1033.      -e prints directories at the End
  1034.      -u must be given exactly two directories. Shows files only in
  1035.         the first directory, files in both and files in the second.
  1036.      -z custom format
  1037.         (must be followed by an argument which holds the format string)
  1038.  
  1039.     Displays a directory of specified files. Default output shows
  1040.     date, protection, block size, byte size and total space used.
  1041.     Protections flags include new 1.2/1.3 flags (see under protect),
  1042.     plus a 'c' flag which indicates that this file has a comment.
  1043.     Files are alphabetically sorted, without case sensitivity, and
  1044.     directories are in red pen (unless you use -c). Dir takes in
  1045.     account the width of your window.
  1046.  
  1047.     To recursively show the contents of a directory and all its
  1048.     sub-directories use the special wildcard pattern ".../*", see
  1049.     section "WILDCARDS" (man wildcards).
  1050.  
  1051.     The lformat string (option -z) is used to create your own directory
  1052.     format. Instead of the "-z lformat" command line argument you can
  1053.     set the variable "_dirformat" (which holds "lformat", but you must
  1054.     set option -z anyhow).
  1055.     Your custom format may contain the following codes:
  1056.      %a age               %l LF if comment      %t time
  1057.      %b size in blocks    %m multi column       %u size in K
  1058.      %c flag c (comment)  %n name               %v dir size in eng.
  1059.      %d date              %o filenote (comment) %w dir size in K
  1060.      %e flag i (.info)    %p name w/ path       %x translated date
  1061.      %f flags "hsparwed"  %q name w/ slash      %+ flag i as '+' or ' '
  1062.      %i flag d (dIr)      %r size in eng.
  1063.      %k class             %s size
  1064.  
  1065.      %I link information (S: softlink, H: hardlink, P: pipe, -: else)
  1066.      %L name of original file if link (empty otherwise)
  1067.      %N name + original name (of link)
  1068.      %F protection bits (flags "rwed") for group/other
  1069.      %U user-id
  1070.      %G group-id
  1071.  
  1072.     Between the '%' and the identifying letter, there may be an optional
  1073.     field width. If the number is preceded by a '-', the field contents
  1074.     will be left adjusted. If by a dot, the contents will be cut down
  1075.     to match the field width if they are longer.
  1076.     If the format string contains a %m, cshell will try to print more
  1077.     than one entry on one line. The column width is the field width of
  1078.     the %m entry. If omitted, it's assumed to be the one of the first
  1079.     file. If a file is longer, it will use two columns.
  1080.  
  1081.     If you prefer the old output-style of this command (5.19 and before)
  1082.     add the following line to your .cshrc file:
  1083.      set _dirformat "   %-24n %c%f %7s %4b %d %t"
  1084.  
  1085.     DISKCHANGE
  1086.  
  1087.     Usage    : diskchange drive...drive
  1088.  
  1089.     Like AmigaDOS diskchange.  Multiple drive names are allowed.
  1090.  
  1091.     ECHO
  1092.  
  1093.     Usage    : echo [-en] string
  1094.     Example    : echo hi there
  1095.     Results    : hi there
  1096.  
  1097.     Options:
  1098.      -n don't append newline.
  1099.      -e echo to stderr.
  1100.  
  1101.     Echo the given string.
  1102.  
  1103.     ELSE
  1104.  
  1105.     Usage    : else ; command
  1106.     Usage    : if -f foo.c ; else ; echo "Not there" ; endif
  1107.  
  1108.     Else clause, must follow an IF statement.
  1109.  
  1110.     ENDIF
  1111.  
  1112.     Usage    : endif
  1113.  
  1114.     The end of an if statement.
  1115.  
  1116.     Note: if you return from a script file with unterminated IF's
  1117.     and the last IF was false, prompt will be changed to an
  1118.     underscore ('_') and no commands will be executed until
  1119.     'endif' is typed.
  1120.  
  1121.     ERROR
  1122.  
  1123.     Usage    : error n
  1124.  
  1125.     Generates return code n.
  1126.  
  1127.     EXEC
  1128.  
  1129.     Usage    : exec [-i] command [args]
  1130.     Example    : set cmdline "dir ram:"
  1131.           exec $cmdline        # would not work without exec
  1132.  
  1133.     Options:
  1134.      -i  return code 0.
  1135.  
  1136.     Execute the command specified; exec command is equivalent to
  1137.     command, only you can use variables to specify command name.
  1138.     Note that the command line is parsed TWICE! Examples:
  1139.      set a dir ram:; exec $a              # right
  1140.      set a mkdir; exec $a "My directory"  # wrong! creates 2 directories
  1141.  
  1142.     Exec returns the return code of the command executed unless
  1143.     option -i (ignore) is set, in which case always 0 is returned.
  1144.  
  1145.     FAULT
  1146.  
  1147.     Usage    : fault error1 .. errorN
  1148.     Example    : fault 205 212
  1149.  
  1150.     Like AmigaDOS fault, prints specified error messages.
  1151.  
  1152.     FILENOTE
  1153.  
  1154.     Usage    : filenote file1 .. fileN  note
  1155.           filenote -s file1...fileN
  1156.  
  1157.     Options:
  1158.      -s (second form) ; displays the file notes of the given files.
  1159.  
  1160.     The first form sets AmigaDOS comment of the specified file.
  1161.  
  1162.     FLIST
  1163.  
  1164.     Usage    : flist
  1165.  
  1166.     Lists the filenumbers of files opened by open.
  1167.     See open and close for more info.
  1168.  
  1169.     FLTLOWER
  1170.  
  1171.     Usage    : fltlower
  1172.     Example    : dir | fltlower
  1173.     Or    : fltlower <readme
  1174.  
  1175.     This is a filter command, i.e. it reads from stdin and writes to
  1176.     stdout. The more natural way to use it is a pipe, or it can be
  1177.     redirected.
  1178.     Its purpose is to convert all alphabetic to lower case.
  1179.  
  1180.     FLTUPPER
  1181.  
  1182.     The same of fltlower, only this converts to upper case.
  1183.  
  1184.     FOREACH
  1185.  
  1186.     Usage    : foreach [-v] varname ( strings ) command
  1187.     Example    : foreach i ( a b c d ) "echo -n $i;echo \" ha\""
  1188.     Result    : a ha
  1189.           b ha
  1190.           c ha
  1191.           d ha
  1192.  
  1193.     Options:
  1194.      -v display arguments every time command is executed. 
  1195.  
  1196.     'strings' is broken up into arguments.  Each argument is placed in
  1197.     the local variable 'varname' in turn and 'command' executed. Put
  1198.     the command(s) in quotes.
  1199.  
  1200.     Foreach is especially useful when interpreting passed arguments in
  1201.     an alias.
  1202.  
  1203.     eg.
  1204.         foreach i ( *.pic ) viewilbm $i
  1205.     assuming a.pic and b.pic in current directory the following commands
  1206.     will occur:
  1207.         viewilbm a.pic
  1208.         viewilbm b.pic
  1209.  
  1210.     All 'for...' commands can be interrupted using CTRL-D or CTRL-E.
  1211.  
  1212.     FOREVER
  1213.  
  1214.     Usage    : forever command
  1215.     or    : forever "command;command;command..."
  1216.  
  1217.     The specified commands are executed over and over again forever.
  1218.  
  1219.     Execution stops if you hit ^C or ^D, or if the commands return with
  1220.     an error code.
  1221.  
  1222.     FORLINE
  1223.  
  1224.     Usage    : forline var filename command
  1225.     or    : forline var filename "command;command..."
  1226.     Example    : forline i RAM:temp "echo line $_linenum=$i"
  1227.  
  1228.     For each ASCII line of file specified commands are executed and
  1229.     var points to line content. You can check system variable _linenum
  1230.     to find the number of the line currently read.
  1231.     If STDIN (case sensitive) is specified as input file, the lines are
  1232.     read from standard input.
  1233.  
  1234.     FORNUM
  1235.  
  1236.     Usage    : fornum [-v] var n1 n2 command
  1237.     or    : fornum [-v] -s var n1 n2 step command
  1238.  
  1239.     Example    : fornum -v x 1 10 echo $x
  1240.     or    : fornum -s x 10 1 -1 echo $x # counts backwards
  1241.  
  1242.     Executes  command(s)  for  all numerical values of x between n1 and
  1243.     n2.   If  more  than  one  command  is  specified,  or  command  is
  1244.     redirected, include command(s) in quotes.
  1245.  
  1246.  
  1247.     Options:
  1248.      -v (verbose) causes printing of progressive numbers.
  1249.      -s specify a step; if negative, the count will be backwards.
  1250.  
  1251.     GETENV
  1252.  
  1253.     Usage    : getenv [shellvar] envvar
  1254.  
  1255.     Gets the value of an ENV: variable and stores it in the shell
  1256.     variable 'shellvar'. If shellvar is omitted, the value of the
  1257.     ENV: variable is printed to stdout.
  1258.     This command is obsolete since ENV: variables can be retrieved
  1259.     by writing $envvar anywhere on the command line.
  1260.  
  1261.     GOTO
  1262.  
  1263.     Usage    : goto label
  1264.     Example    :
  1265.           label start
  1266.             echo "At start"
  1267.             dir ram:
  1268.             goto start
  1269.  
  1270.     Goto  the specified label name.  You can only use this command from
  1271.     a  source  file.   Labels  may  be  forward or reverse from current
  1272.     position. It is legal to jump out of if's.
  1273.  
  1274.     HEAD
  1275.  
  1276.     Usage    : head [filename] [num]
  1277.     Example    : head readme 20
  1278.  
  1279.     Display first "num" lines of "filename".   If num is not specified,
  1280.     10 is assumed. If filename is not specified, standard input (stdin)
  1281.     is taken instead.
  1282.  
  1283.     HELP
  1284.  
  1285.     Usage    : help [-f]
  1286.     Example    : help
  1287.     Options    :
  1288.      -f list functions also
  1289.  
  1290.     Simply  displays  all  the  available  commands.   The commands are
  1291.     displayed in search-order.  That is, if you give a partial name the
  1292.     first  command  that  matches  that  name  in  this list is the one
  1293.     executed.   Generally,  you  should  specify enough of a command so
  1294.     that it is completely unique.
  1295.  
  1296.     HISTORY
  1297.  
  1298.     Usage    : history [-nr] [partial_string]
  1299.     Example    : history
  1300.  
  1301.     Options    :
  1302.      -n omits line numbering
  1303.      -r reads history from stdin
  1304.  
  1305.     Displays  the  enumerated  history  list.   The size of the list is
  1306.     controlled  by  the  _history  variable.   If you specify a partial
  1307.     string, only those entries matching that string are displayed.
  1308.  
  1309.     HOWMANY
  1310.  
  1311.     Usage    : howmany
  1312.  
  1313.     This  command  tells you how many instances of Shell are running in
  1314.     your system.
  1315.  
  1316.     HTYPE
  1317.  
  1318.     Usage    : htype [-r] [file1..fileN]
  1319.  
  1320.     Options:
  1321.      -r display all files in a directory.
  1322.  
  1323.     Displays the specified files in hex and ASCII, just like the system
  1324.     command 'Type file opt h'.  Especially suitable for binary files.
  1325.  
  1326.     If there are no filenames specified, standard input is used,
  1327.     so you can use htype as the destination for a pipe.
  1328.  
  1329.     IF
  1330.  
  1331.     Usage    : if [-n] argument conditional argument [then]
  1332.     or    : if [-n] argument
  1333.     or    : if [-n] -f file    or   -e file
  1334.     or    : if [-n] -d file/dir
  1335.     or    : if [-n] -m
  1336.     or    : if [-n] -t file file1 .. fileN
  1337.     or    : if [-n] -r rpnexpression
  1338.     or    : if [-n] -v varname
  1339.     or    : if [-n] -o char arg ... arg
  1340.  
  1341.     Options:
  1342.      -n (NOT) reverses the result.
  1343.      -d tests the type of the object specified: if it is a
  1344.         directory, then TRUE; if it is a file (or it doesn't exist)
  1345.         then FALSE.
  1346.      -f (or -e) checks for existance of the specified file.
  1347.      -m test if FAST memory is present.
  1348.      -o tests for option 'char' in the rest of the arguments.
  1349.      -r evaluates a given RPN expression (see under RPN for more info).
  1350.         If value on top of stack is 0, then FALSE, else TRUE.
  1351.      -t compare the date and time of the first file with all the others;
  1352.         if the first is younger than ALL the others, then FALSE,
  1353.         else TRUE. If a file doesn't exists, it is considered as
  1354.         being older.
  1355.      -v test if a given variable is defined.
  1356.  
  1357.  
  1358.     Makes the following instructions up to the next endif conditinal.
  1359.     The 'then' is optional. The if clause must be followed by a semi-
  1360.     colon if instructions follow on the same line.
  1361.  
  1362.     If a single argument is something to another argument.  Conditional
  1363.     clauses allowed:
  1364.  
  1365.     <, >, =, ! and combinations.  Thus != is not-equal, >= larger or
  1366.     equal, etc...
  1367.  
  1368.     If arguments are not numeric, they are compared as strings.
  1369.  
  1370.     Usually the argument is either a constant or a variable ($varname).
  1371.  
  1372.     The second form of IF is conditional on the existence of the
  1373.     argument.  If the argument is a "" string, then FALSE, else TRUE.
  1374.  
  1375.     The third form of IF used by -f switch checks for existance of
  1376.     the specified file. -e is the same as -f
  1377.  
  1378.     Option -m is used to test if FAST memory is present.
  1379.     Example (to be included in a login.sh file):
  1380.     if -m; resident -d lc1 lc2 blink; endif
  1381.  
  1382.     Using -t form compares the date and time of the first file with
  1383.     all the others; if the first is younger than ALL the others, then
  1384.     FALSE, else TRUE. If a file doesn't exists, it is considered as
  1385.     being older.
  1386.     This feature is especially useful for building makefiles without
  1387.     using any MAKE utility.
  1388.  
  1389.     Example:
  1390.     if -t test.o test.asm test.i ; asm -o test.o test.asm ; endif
  1391.  
  1392.  
  1393.     Option -o tests for option 'char' in the rest of the arguments.
  1394.  
  1395.     Example: if -o r -rp ram:comm1.c     will yield TRUE.
  1396.  
  1397.     When using 'IF' command interactively if you are entering commands
  1398.     following an 'IF' that was false, the prompt will be set to a
  1399.     underscore '_ ' to indicate all commands will be ignored until
  1400.     an 'ELSE' or 'ENDIF' command is seen.
  1401.  
  1402.     INC
  1403.  
  1404.     Usage    : inc varname [value]
  1405.     Example    : inc abc 5
  1406.  
  1407.     Increment the numerical equivalent of the variable with specified
  1408.     value (default: 1) and place the ASCII-string result back into
  1409.     that variable.
  1410.  
  1411.     INFO
  1412.  
  1413.     Usage    : info [-pt] [path1 path2 ... pathN]
  1414.  
  1415.     Options    :
  1416.      -p  only display drives with readable (present) disks
  1417.      -t  print disk/fs type and bytes used instead of block sizes
  1418.  
  1419.     If called without arguments, info gives you the drive information
  1420.     on all devices. If one or more paths are specified, only infor-
  1421.     mation on those drives will be displayed.
  1422.  
  1423.     Note: Cshell does (correct) rounding for all displayed values,
  1424.           Commodore's Info command does not. So values may slightly
  1425.           change.
  1426.  
  1427.     INPUT
  1428.  
  1429.     Usage    : input [-sr] var var ... var
  1430.     Example    : input abc
  1431.  
  1432.     Options    :
  1433.      -s the whole line is read in as one word, including spaces.
  1434.      -r puts the console to single character mode before reading,
  1435.         ie. does not wait for RETURN to be pressed). Use with care.
  1436.  
  1437.     Input from STDIN (or a redirection, or a pipe) to a variable.  The
  1438.     next input line is broken up in words (unless quoted) and placed in
  1439.     the variable. 
  1440.  
  1441.     JOIN
  1442.  
  1443.     Usage    : join [-r] file1..fileN destfile
  1444.     Example    : join part1 part2 part3 total
  1445.  
  1446.  
  1447.     Options    :
  1448.      -r overwrite any existent destfile.
  1449.  
  1450.     Joins (concatenates) the specified files to get destfile. Join
  1451.     will refuse to overwrite an existing destfile, unless the 
  1452.     'r' option is used. 
  1453.  
  1454.     KEYMAP
  1455.  
  1456.     Usage    : keymap [number {key=function}]
  1457.     Example    : keymap 0 1030=4 1032=12
  1458.  
  1459.     Defines one keymap for the csh command line editing. See chapter XV.
  1460.  
  1461.     LABEL
  1462.  
  1463.     Usage    : label name
  1464.  
  1465.     Create a program label right here. Used in source files, you can
  1466.     then GOTO a label.
  1467.  
  1468.     LINECNT
  1469.  
  1470.     Another filter. Counts the number of lines of its stdin and writes
  1471.     it to stdout.
  1472.  
  1473.     LN (or MAKELINK)
  1474.  
  1475.     Usage    : ln [-s] filename [linkname]
  1476.     Example    : ln stuff/data newname
  1477.  
  1478.     Options    :
  1479.      -s make soft link (default is hard link)
  1480.  
  1481.     ln creates an additional directory entry, called a link,  to
  1482.     a file or directory.  Any number of links can be assigned to
  1483.     a file.
  1484.  
  1485.     filename is the name of  the  original  file  or  directory.
  1486.     linkname  is  the  new  name  to  associate with the file or
  1487.     filename.  If linkname is omitted,  the  last  component  of
  1488.     filename is used as the name of the link.
  1489.  
  1490.     A hard link (the default) is a standard directory entry just
  1491.     like the one made when the file was created.  Hard links can
  1492.     only be made to existing files.  Hard links cannot  be  made
  1493.     across file systems (disk partitions, mounted file systems).
  1494.     To remove a file, all hard links  to  it  must  be  removed,
  1495.     including  the  name by which it was first created; removing
  1496.     the last hard link releases the inode  associated  with  the
  1497.     file.
  1498.  
  1499.     A symbolic link, made with  the  -s  option,  is  a  special
  1500.     directory entry that points to another named file.  Symbolic
  1501.     links can span file systems and point  to  directories.   In
  1502.     fact,  you  can create a symbolic link that points to a file
  1503.     that is currently absent from the file system; removing  the
  1504.     file that it points to does not affect or alter the symbolic
  1505.     link itself.
  1506.  
  1507.     NOTE: Symbolic links (also known as "soft links") are
  1508.           currently NOT SUPPORTED by AmigaOS.  DO NOT USE!
  1509.  
  1510.     LOCAL
  1511.  
  1512.     Usage: local [var...var]
  1513.  
  1514.     Creates one or more local variables. Those variables disappear
  1515.     at the end of their alias or source file, and cannot be accessed
  1516.     from inside other aliases or source files.
  1517.     With no arguments, shows all top level variables and their values.
  1518.  
  1519.     LS (or DIR)
  1520.  
  1521.     Equivalent to DIR.
  1522.  
  1523.     MAKELINK (or LN)
  1524.  
  1525.     Equivalent to LN.
  1526.  
  1527.     MAN
  1528.  
  1529.     Usage    : man command(s)
  1530.     Example    : man mkdir
  1531.  
  1532.     Get  info about a Shell command, or others keywords.  These include
  1533.     all  special  _variables, plus various keywords:  WILDCARDS, PIPES,
  1534.     EDITING, STARTUP and more.
  1535.     See special alias manlist to get a list of ALL keywords supported
  1536.     by man.
  1537.     You  must set _man to the paths of your .doc files:
  1538.        set _man dh1:docs/aliases.doc dh1:docs/csh.doc
  1539.  
  1540.     To create your own .doc files, precede all your keywords by four
  1541.     blanks. 'man' will then display lines until the first character
  1542.     of a line is alphanumeric or has four leading blanks.
  1543.  
  1544.     MD (or MKDIR)
  1545.  
  1546.     Equivalent to MKDIR.
  1547.  
  1548.     MEM
  1549.  
  1550.     Usage    : mem [-cfqsl]
  1551.  
  1552.     Options:
  1553.       -c shows the free chip mem only
  1554.       -f shows the free fast mem only
  1555.       -q outputs just a number without titles
  1556.       -s stores current free memory
  1557.       -r shows memory used relative to last stored
  1558.       -l flushes all unneeded memory
  1559.  
  1560.     MENU
  1561.  
  1562.     Usage    : menu [-mn] [ title item...item ]
  1563.     Example    : menu Shell   JrComm,,j   Rename,"rename ",r  quit
  1564.  
  1565.     Options:
  1566.      -n clear all existing menus.
  1567.      -m use monospaced font.
  1568.  
  1569.     Appends one pull down in the current console window. Up to 31
  1570.     menus with 63 items each (including title) can be installed.
  1571.  
  1572.     If the item is just a string, that string will be in the menu item.
  1573.     When you select it, it will be put into the prompt and executed.
  1574.  
  1575.     If there is a comma and after that comma a second string, this
  1576.     will be the command will be inserted at the prompt. This time you
  1577.     have to add the ^M yourself if you want the command to be executed.
  1578.  
  1579.     If there is a second comma, the letter after that comma will be
  1580.     the keyboard shortcut for that menu item. (This will be case
  1581.     sensitive some day, use lowercase).
  1582.  
  1583.     If for any reason your current menu is corrupt, just enter an
  1584.     empty 'menu' command.
  1585.  
  1586.     When the first menu is installed you can use option -m to choose
  1587.     a monospaced font (System Default Font) instead of the default
  1588.     Intuition Font (which may be a proportional font). This is useful
  1589.     for user-formatted menus (like in the example script "menu.sh").
  1590.  
  1591.     MKDIR (or MD)
  1592.  
  1593.     Usage    : mkdir [-p] name name name...
  1594.     Example    : mkdir df0:stuff
  1595.  
  1596.     Options:
  1597.      -p create all dirs in path if necessary.
  1598.  
  1599.     Create the specified directories.
  1600.     If "name" ends with trailing slash it will be stripped off.
  1601.  
  1602.     mkdir now supports the -p option.  mkdir -p followed by a full path
  1603.     name will create all directories necessary to make the path.  For
  1604.     example, suppose that the directory ram:foo exists and is empty.
  1605.     "mkdir -p ram:foo/bar/tst/a" would create ram:foo/bar,
  1606.     ram:foo/bar/tst, and ram:foo/bar/tst/a all in one step.
  1607.     In addition, it will issue no error codes for directories it cannot
  1608.     make.
  1609.  
  1610.     MV (or RENAME)
  1611.  
  1612.     Equivalent to RENAME.
  1613.  
  1614.     OPEN
  1615.  
  1616.     Usage    : open filename filemode filenumber
  1617.     Example    : open RAM:data w 1
  1618.  
  1619.     This  allows you to open a file, redirect to it as many commands as
  1620.     you like, then close it.
  1621.     Filename is any valid AmigaDOS filename, filemode is either "r" for
  1622.     read or "w" for write, filenumber is a number between 1 and 10.
  1623.     To  redirect  a  program to or from an open file, use as your redir
  1624.     filename a dot followed by the filenumber.
  1625.     Here is a complete example:
  1626.  
  1627.         open RAM:data w 1
  1628.         echo -n 2+2= >.1
  1629.         rpn 2 2 + . CR >.1
  1630.         close 1
  1631.         type RAM:data    # will display 2+2=4
  1632.  
  1633.     See also close, flist.
  1634.  
  1635.     PATH
  1636.  
  1637.     Usage    : path [-gr] [dir...dir]
  1638.  
  1639.     Without arguments, lists AmigaDOS path. Otherwise adds given
  1640.     directories to the path, preventing duplicate entries.
  1641.  
  1642.     Options:
  1643.      -r Resets the path
  1644.      -g Global path modifications; operations (add, reset) apply to all
  1645.          CLI processes instead of only the current one
  1646.  
  1647.     Note:
  1648.     It's not perfectly "legal" to modify the path-list of other
  1649.     processes. Adding entries (option -g) works fine in most cases.
  1650.     But the removal of entries (options -gr together) may crash the
  1651.     system, because CSH doesn't know about the memory handling of
  1652.     other processes (it doesn't know how they allocated the memory
  1653.     for the path-list entries).
  1654.  
  1655.     So use option -g always with care (at least together with -r).
  1656.     If it works, it's okay. If not, you lose ;-)  There's no 100%
  1657.     reliable way for global path modifications.
  1658.  
  1659.     PRI
  1660.  
  1661.     Usage    : pri clinumber pri
  1662.     Example    : pri 3 5    # set priority of cli #3 to 5
  1663.  
  1664.     Change the priority of the specified task (use PS command to
  1665.     determine clinumber). If you specify 0 as clinumber you can
  1666.     change priority of "this" task (the one executing shell).
  1667.  
  1668.     PROTECT
  1669.  
  1670.     Usage    : protect file1 ... filen [u|g|o|a][+|-|=][flags]
  1671.     Example    : protect myfile u+rwe
  1672.  
  1673.     Set AmigaDOS file protection flags for the file specified.
  1674.     Valid flags are h, s, p, a, r, w, e, d.  (x is the same as e)
  1675.  
  1676.     Ownership:
  1677.       u  Set specified bits for User
  1678.       g  Set specified bits for Group
  1679.       o  Set specified bits for Other (not User, not Group)
  1680.       a  all, alias for "ugo" (User/Group/Other)
  1681.     Specifying no ownership is equal to 'u'.
  1682.  
  1683.     Modes:
  1684.       +  Set specified bits, leave all others
  1685.       -  Clear specified bits, leave all others
  1686.       =  Set specified bits, clear all others
  1687.     Specifying no mode is equal to '='.
  1688.  
  1689.     Archive bit cleared by default!
  1690.  
  1691.     Note: This command is equivalent to "chmod" except that the
  1692.           arguments for filename(s) and flag(s) are reversed.
  1693.  
  1694.     PS
  1695.  
  1696.     Usage    : ps [-les] [commandname...commandname]
  1697.  
  1698.     Options:
  1699.      -l shows full pathnames of commands
  1700.      -e excludes the given command names from the list
  1701.      -s don't show stacksize and type, use old output-format instead
  1702.  
  1703.     Gives status of CLI processes.  eg:
  1704.  
  1705.     Proc Command Name         Typ  Stack  Pri.  Address  Directory
  1706.     * 1  csh                  fr   10000    0      97b0  Stuff:shell
  1707.       2  clock                bw    4096  -10    2101a8  Workdisk:
  1708.       3  emacs                bw   30000    0    212f58  Stuff:shell
  1709.       4  VT100                bw    4000    0    227328  Workdisk:
  1710.  
  1711.     Address is the address of the task, directory is the process
  1712.     currently CD'd directory. My default, only the BaseNames of
  1713.     the commands are shown. Your own CLI will be marked by an
  1714.     asterisk in the first column.
  1715.  
  1716.     Stack size is the _real_ size of a command's stack. It's _not_
  1717.     the size a program gets if it's launched by this command.  Use
  1718.     "Status" instead if you need the size of the Default Stack.
  1719.     (be aware: "Status" does _not_ show the stack size used by a prog!)
  1720.  
  1721.     Typ are two letters.  The first is either "f" (foreground) or
  1722.     "b" (background).  The second is one of:
  1723.         i: invalid
  1724.         a: added
  1725.         r: running / ready to run
  1726.         w: waiting
  1727.         e: except
  1728.         d: removed
  1729.  
  1730.     PWD
  1731.  
  1732.     Usage    : pwd
  1733.  
  1734.     Rebuild _cwd by backtracing from your current directory.
  1735.  
  1736.     QSORT
  1737.  
  1738.     Usage    : qsort [-cr] <in >out
  1739.  
  1740.     Options :
  1741.      -c case-sensitive
  1742.      -r reverse sort
  1743.  
  1744.     Quick sorts from stdin to stdout (case-insensitive).
  1745.  
  1746.     QUIT
  1747.  
  1748.     Usage    : quit
  1749.  
  1750.     Quit out of Shell back to CLI.
  1751.  
  1752.     RBACK
  1753.  
  1754.     Usage    : rback command
  1755.  
  1756.     Start a new process executing the specified command, but can't do
  1757.     input/output. Equivalent to 'run command >NIL: <NIL:'. Instead of
  1758.     using rback, you can add a '&' at the end of the command line.
  1759.  
  1760.     Note: rback cannot start builtin commands. You have to start a
  1761.           subshell: rback csh -c "copy ram:temp prt:;rm ram:temp
  1762.  
  1763.     READFILE
  1764.  
  1765.     Usage    : readfile varname [filename]
  1766.  
  1767.     Completely reads an ASCII file and assigns it to a variable. Each
  1768.     line becomes one word in the resulting string. Embedded blanks
  1769.     are no problem. If file name is omitted, stdin is used. See also
  1770.     'writefile', @subfile and @flines
  1771.  
  1772.     REHASH
  1773.  
  1774.     Usage    : rehash [-cglos]
  1775.  
  1776.     Options :
  1777.      -c clear local program hash list
  1778.      -g clear global program hash list
  1779.      -l load global program hash list into local buffer
  1780.      -o output local program hash list
  1781.      -s save local program hash list to disk
  1782.  
  1783.     Scans the complete DOS search path (see also 'path') and builds a
  1784.     program hash list. This can be used for program name completion from
  1785.     command line (default: ESC-p, ESC-P). And when running commands
  1786.     CShell does not scan DOS search path any more for every command but
  1787.     instead scans the program hash list in memory (minimizes disk access
  1788.     and speeds up running commands significantly).
  1789.  
  1790.     Of course, when you add a directory to your path, when you add
  1791.     programs to the existing path or when you remove directories/programs
  1792.     then you have to rebuild the program hash list.
  1793.  
  1794.     Each invocation of CShell has its own local buffer to hold that
  1795.     program hash list.  Use option -s to save the local list to disk
  1796.     (csh:csh-prgs).  With option -l the list is loaded into memory.
  1797.     The first CShell loading the list puts a copy of it into a global
  1798.     buffer so that next time a CShell wants to load it the global buffer
  1799.     is used and not the disk file.
  1800.  
  1801.     The global list stays in memory -- even if you quit all CShells.
  1802.     Use option -g to free that global list (if you are low on memory),
  1803.     but this does not affect local lists of any currently running CShell.
  1804.     Option -c clears the local list.
  1805.  
  1806.     If you run this command without options the scanned list is not only
  1807.     put into local buffer but also in global buffer.
  1808.  
  1809.     There's no need to clear the local/global list before
  1810.     loading/building a new one. This is done automatically.
  1811.  
  1812.     The variable $_prghash (default: 'csh:csh-prgs') holds the filename
  1813.     where the program hash list is loaded from and saved to.
  1814.  
  1815.     Programs from the hash list are case in-sensitive and may be
  1816.     abbreviated. This can be toggled with the variable "_abbrev".
  1817.     
  1818.     Recommended usage:
  1819.     First run "rehash" from your shell to build the program hash list.
  1820.     Save this list to disk with "rehash -s".  Now include "rehash -l"
  1821.     in "s:.cshrc" to load this list on every invocation of CShell.
  1822.  
  1823.     RELABEL
  1824.  
  1825.     Usage    : relabel drive name
  1826.     Example    : relabel DH0: Picard
  1827.  
  1828.     Change the volume name of the disk in the given drive to the name
  1829.     specified. Volume names are set initially when you format a disk.
  1830.  
  1831.     If you have a floppy disk system with only one disk drive, be sure
  1832.     to specify the disks by volume name, instead of drive name.
  1833.  
  1834.     RENAME (or MV)
  1835.  
  1836.     Usage    : rename [-fv] from to
  1837.     or    : rename [-fv] from from from ... from todir
  1838.  
  1839.     Options :
  1840.      -f don't abort on errors
  1841.      -v verbose mode (print renamed filenames)
  1842.  
  1843.     Allows you to rename a file or move it around within a disk.
  1844.     Allows you to move 1 or more files into a single directory.
  1845.     The archive bit of the file(s) will be cleared.
  1846.  
  1847.  
  1848.     RESIDENT
  1849.  
  1850.     Usage    : resident [-dr] [files]
  1851.     Example    : resident lc1 lc2 blink    # load these as resident
  1852.           resident -d lc1 lc2 blink    # defer load when needed
  1853.           resident -r lc1 lc2 blink    # remove these
  1854.           resident            # list resident programs
  1855.  
  1856.  
  1857.     Options :
  1858.      -d deferred load; 
  1859.      -r remove files from resident list
  1860.  
  1861.     This is DOS resident. Commands are searched by Shell in resident
  1862.     list BEFORE of searching on any external device.
  1863.     Only PURE programs can run as resident, see DOS docs for more info.
  1864.     Option -d is very useful: you can say, in your startup file,
  1865.     resident -d file...file; programs will not be loaded immediately,
  1866.     but only when you will try to load them. This way, you will not
  1867.     waste memory and startup time if you don't use the programs.
  1868.     Old option -a has no more effect.
  1869.  
  1870.     RETURN
  1871.  
  1872.     Usage    : return [n]
  1873.     Example    : return 10
  1874.  
  1875.     Exit from a script file, or quit from shell with optional
  1876.     exit code.
  1877.  
  1878.     RM (or DELETE)
  1879.  
  1880.     Equivalent to DELETE.
  1881.  
  1882.     RPN
  1883.  
  1884.     Usage    : rpn expression
  1885.     Example    : rpn 3 7 *    # Prints the value 21
  1886.  
  1887.     Evaluate an RPN expression, using 32-bit values. In older versions
  1888.     of Shell RPN contained string functions too, but now that strings
  1889.     are handled by specifical commands, these are no more needed.
  1890.     At end of evaluation, RPN prints values on stack, so you can
  1891.     say for instance "rpn $x 2 * | input x" to double the value of
  1892.     variable x.
  1893.     Functions implemented are:
  1894.  
  1895.         + - * /    Obvious meaning; / means integer division, of course
  1896.         %        Module operator e.g. "rpn 7 3 %" answers 1
  1897.         & | ~    Bitwise and, or, not operators
  1898.         > < ==    Tests for greater-than, lower-than, equal. To get
  1899.             a test for >= (or <=), you can use < ! (or > !)
  1900.         !        Logical not operator
  1901.         DUP        Duplicate value on top of stack
  1902.         DROP    Drop value on top of stack
  1903.         SWAP    Swap two values on top of stack
  1904.  
  1905.     To avoid confusion with redirections, > and < operators must be
  1906.     enclosed in quotes e.g.
  1907.  
  1908.         3 2 ">"        # Prints 1
  1909.  
  1910.     RUN
  1911.  
  1912.     Usage    : run prgm args
  1913.     Example    : run emacs test.c
  1914.  
  1915.     Start a new process executing the specified command. This command is
  1916.     not fully reliable: use at your own risk.  See also rback.
  1917.  
  1918.     RXREC
  1919.  
  1920.     Usage    : rxrec [portname]
  1921.  
  1922.     Create an AREXX-compatible port of the specified name (defaults to
  1923.     "rexx_csh"), then puts Shell to sleep waiting for messages on it.
  1924.  
  1925.     CAUTION: the only way to exit from this status is to send to the
  1926.     port the message "bye".
  1927.  
  1928.     Example:
  1929.     Open two Shell's in two separate CLI's. From the first, type:
  1930.  
  1931.         rxrec
  1932.  
  1933.     Now first Shell doesn't respond to keyboard input; instead, it waits
  1934.     for messages on a port called "rexx_csh". Now, from the other, type:
  1935.  
  1936.         rxsend rexx_csh "dir df0:"
  1937.  
  1938.     You will see the listing of df0: in the first Shell.  Experiment as
  1939.     you like, then:
  1940.  
  1941.         rxsend rexx_csh bye
  1942.  
  1943.     And all will return to normal.
  1944.  
  1945.     RXSEND
  1946.  
  1947.     Usage    : rxsend [-lr] portname command...command
  1948.  
  1949.     Options :
  1950.      -r set the variable _result to the result string of the 
  1951.         AREXX command.
  1952.      -l send the whole line as *one* command.
  1953.  
  1954.     Send commands to any program with an AREXX-compatible port. Be aware
  1955.     that every word is sent as a single command!
  1956.  
  1957.     You don't have to load anything to use these command (or rxrec):
  1958.     all you need is a program with the right port.
  1959.  
  1960.     An example is CygnusEdProfessional: here is, for instance, a command
  1961.     to wake it up, load the file test.c and jump to line 20:
  1962.  
  1963.         rxsend rexx_ced cedtofront "open test.c" "jmp to line 20"
  1964.         # rexx_ced is the name of AREXX port for CygnusEd
  1965.  
  1966.  
  1967.     Refer to your application manual for details and for the names
  1968.     of the commands and the port.
  1969.  
  1970.     SEARCH
  1971.  
  1972.     Usage    : search [-abceflnoqrvw] file...file string
  1973.  
  1974.     Search specified files for a string. Only lines containing the
  1975.     specified strings are displayed.
  1976.  
  1977.     If the filename is STDIN (in uppercase), the standard input is
  1978.     used, so you can use search as the destination for a pipe.
  1979.     Example:
  1980.         strings myprog * | search STDIN .library
  1981.     Lists all libraries used in "myprog".
  1982.  
  1983.     Search is very fast if none of the options -w, -e and STDIN was
  1984.     specified and the file fits into memory.
  1985.  
  1986.     Options:
  1987.       -a (abort)   stops search as soon as the pattern was found once
  1988.       -b (binary)  shows only byte offsets instead of lines. If combined
  1989.                    with -n, shows naked numbers.
  1990.       -c (case)    turns ON case sensitivity
  1991.       -e (exclude) lists lines NOT containing the pattern
  1992.       -f (files)   causes only the names of the files in which the pat-
  1993.                    tern was found to be displayed.
  1994.       -l (left)    pattern must be at beginning of line (this is faster
  1995.                    than using a wild card)
  1996.       -n (number)  turns off line numbering
  1997.       -o (only)    finds only whole words
  1998.       -q (quiet)   suppresses printing of file names.
  1999.       -r (recurse) if you specify any directory, all files in that di-
  2000.                    rectory are recursively searched.
  2001.       -v (verbose) shows each file name on a single line. this is auto-
  2002.                    matically turned on if search is redirected
  2003.       -w (wild)    wild card matching. see notes below
  2004.  
  2005.     Notes to wild card matching;
  2006.     - Uses Shell standard matching.
  2007.     - All standard DOS wildcards are allowed * ? [] () | ~ ' #
  2008.     - The WHOLE line must match the string, not only a substring.
  2009.     - String MUST be enclosed in quotes to avoid wildcard expansion
  2010.  
  2011.     Examples:
  2012.         search -cr df0:include ACCESS
  2013.     Find all occurrences of ACCESS (in uppercase) in all files
  2014.     contained in include directory.
  2015.         search -w shell.h "'#define*"
  2016.     Lists only lines of file beginning with (not simply containing)
  2017.     #define. Note the use of ' to escape the special symbol #.
  2018.  
  2019.     SET
  2020.  
  2021.     Usage    : set [name] [=] [string]
  2022.     Example    : set abc hello
  2023.  
  2024.     Set with no args lists all current variable settings.
  2025.     Set with one arg lists the setting for that particular variable.
  2026.     Specifying name and string, stores the string into variable name.
  2027.  
  2028.     Also see the section on special _variables.
  2029.  
  2030.     SETENV
  2031.  
  2032.     Usage    : setenv envvar value
  2033.  
  2034.     Sets an ENV: variable to the given value. The value must be
  2035.     enclosed in quotes if it contains spaces. To retrieve an ENV:
  2036.     variable, just use $envvar anywhere on a command line.
  2037.  
  2038.     SLEEP
  2039.  
  2040.     Usage    : sleep timeout
  2041.     Example    : sleep 10
  2042.  
  2043.     Sleep for 'timeout' seconds, or until ^C typed.
  2044.  
  2045.     SOURCE
  2046.  
  2047.     Usage    : source file [arguments]
  2048.     Example    : source mymake.sh all
  2049.     Result    : batch file 'mymake.sh' called with var _passed = 'all'
  2050.  
  2051.     Execute commands from a file.  You can create SHELL programs in
  2052.     a file and then execute them with this command.  Source'd files
  2053.     have the added advantage that you can have loops in your command
  2054.     files (see GOTO and LABEL).  You can pass SOURCE files arguments
  2055.     by specifying arguments after the file name.  Arguments are passed
  2056.     via the _passed variable (as a single string, a set of words).
  2057.     See _failat variable for script aborting.
  2058.  
  2059.     Long lines may be split by appending a backslash (\) at end of
  2060.     first part. One single line must be shorter than 512 bytes, but
  2061.     the concatenated line can be as long as you want. There is no
  2062.     limit on the length of the concatenated line.
  2063.  
  2064.     Automatic 'sourcing' is accomplished by appending a .sh suffix to
  2065.     the file (no need to set the s-bit) and executing it as you would
  2066.     a C program:
  2067.  
  2068.     --------- file hello.sh ---------
  2069.     foreach i ( $_passed ) "echo yo $i"
  2070.     ---------------------------------
  2071.  
  2072.     $ hello a b c
  2073.     yo a
  2074.     yo b
  2075.     yo c
  2076.  
  2077.     If the last character of a line in a source file is '{', all
  2078.     following lines will appended to the current one and separated
  2079.     by semicolons until the last character of a line is '}'. Those
  2080.     blocks may be nested. You may use comments and unterminated
  2081.     strings within.
  2082.  
  2083.     --------- file login.sh ---------
  2084.     alias complex {
  2085.       echo -n "this alias
  2086.       echo " works!"
  2087.     }
  2088.     ---------------------------------
  2089.  
  2090.     $ login
  2091.     $ complex
  2092.     this   alias   works!
  2093.  
  2094.     SPLIT
  2095.  
  2096.     Usage    : split srcvar dstvar...dstvar
  2097.  
  2098.     Assigns one word of srcvar to every dstvar, the rest of srcvar to
  2099.     the last dstvar.
  2100.     Note: You enter variable NAMES, not variables.
  2101.  
  2102.     STACK
  2103.  
  2104.     Usage    : stack [number]
  2105.     Example    : stack [-s] 8000
  2106.  
  2107.     Options :
  2108.      -s prints size only (pure number, no text).
  2109.  
  2110.     Changes the default stack for this CLI.
  2111.     Without arguments, just prints it.
  2112.  
  2113.     STRHEAD
  2114.  
  2115.     Usage    : strhead varname breakchar string
  2116.     Example    : strhead x . foobar.bas    # Will set x to "foobar"
  2117.  
  2118.     Remove everything after and including the breakchar in 'string' and
  2119.     place in variable 'varname'.
  2120.  
  2121.     STRINGS
  2122.  
  2123.     Usage    : strings [-bnrv] [file1..fileN] [minlength]
  2124.     Example    : strings [-bnrv] c:dir c:list shell 7
  2125.  
  2126.     Options :
  2127.      -r  if you specify any directory, all files in that directory
  2128.          are recursively searched for strings
  2129.      -n  print name of current file in front of each string
  2130.      -b  shows each string enclosed by  '|' characters, so as to expose
  2131.          leading and trailing spaces or tabs.
  2132.      -v  verbose output before each file (filename, minlength)
  2133.  
  2134.     Prints strings contained in specified files (usually binary)
  2135.     with length >= minlength.  Default is 4.
  2136.  
  2137.     You cannot use a filename that represents a number as last
  2138.     argument. If there are no filenames specified, standard input
  2139.     is used, so you can use strings as the destination for a pipe.
  2140.  
  2141.     STRLEFT
  2142.  
  2143.     Usage    : strleft varname string n
  2144.     Example    : strleft x LongString 5    # Will set x to "LongS"
  2145.  
  2146.     Place leftmost n chars of string in variable varname.
  2147.  
  2148.     STRLEN
  2149.  
  2150.     Usage    : strlen varname string
  2151.     Example    : strlen x Hello        # Will set x to "5"
  2152.  
  2153.     Puts len of string in variable varname.
  2154.  
  2155.     STRMID
  2156.  
  2157.     Usage    : strmid varname string n1 [n2]
  2158.     Example    : strmid x LongString 5 3    # Will set x to "Str"
  2159.  
  2160.     Places n2 chars from string, starting at n1, in variable varname.
  2161.     By omitting n2, you get all chars from n1 to end of string.
  2162.  
  2163.     STRRIGHT
  2164.  
  2165.     Usage    : strright varname string n
  2166.     Example    : strright x LongString 5    # Will set x to "tring"
  2167.  
  2168.     Place rightmost n chars of string in variable varname.
  2169.  
  2170.     STRTAIL
  2171.  
  2172.     Usage    : strtail varname breakchar string
  2173.     Example    : strtail x . foobar.bas    # Will set x to "bas"
  2174.  
  2175.     Remove everything before and including the breakchar in 'string' and
  2176.     place in variable 'varname'.
  2177.  
  2178.     TACKON (or ADDPART)
  2179.  
  2180.     Usage    : tackon var pathname filename
  2181.     Example    : tackon x df0:c Dir    # sets x to "df0:c/Dir"
  2182.     or    : tackon x df0: Preferences #sets x to "df0:Preferences"
  2183.  
  2184.     Correctly  adds  a  filename  to a pathname, and puts the result in
  2185.     variable specified.
  2186.  
  2187.     TAIL
  2188.  
  2189.     Usage    : tail [filename] [num]
  2190.     Example    : tail readme 20
  2191.  
  2192.     Display last "num" lines of "filename".    If num is not specified,
  2193.     10 is assumed. If filename is not specified, standard input (stdin)
  2194.     is taken instead.
  2195.  
  2196.     TEE
  2197.  
  2198.     Usage    : tee [file]
  2199.     Example    : cc test.c | tee >error.list
  2200.  
  2201.     Copies stdin to stdout and the given file.
  2202.     If file is omitted, stderr is used.
  2203.  
  2204.     TOUCH
  2205.  
  2206.     Usage    : touch file1 .. fileN
  2207.  
  2208.     Sets DateStamp of the specified files to the current date & resets
  2209.     archive bit.
  2210.  
  2211.     If a file doesn't exist, touch will create an empty one for you.
  2212.  
  2213.     TRUNCATE
  2214.  
  2215.     Usage    : truncate [n]
  2216.     Example : alias | qsort | truncate
  2217.  
  2218.     A filter that truncates the width of stdin to the specified number,
  2219.     trying to account for tab's and escape sequences. If the number is
  2220.     omitted, the current window width is used.
  2221.  
  2222.     TYPE (or CAT)
  2223.  
  2224.     Equivalent to CAT.
  2225.  
  2226.     UNALIAS
  2227.  
  2228.     Usage    : unalias name .. name
  2229.     Example    : unalias vt
  2230.  
  2231.     Delete aliases..
  2232.  
  2233.     UNIQ
  2234.  
  2235.     Usage    : uniq
  2236.  
  2237.     This is a  filter that removes consecutive, duplicated lines in a
  2238.     file.  It is most useful on a sorted file.
  2239.  
  2240.     UNSET
  2241.  
  2242.     Usage    : unset name .. name
  2243.     Example    : unset abc
  2244.  
  2245.     Unset one or more variables.  Deletes them entirely.
  2246.  
  2247.     USAGE
  2248.  
  2249.     Usage    : usage [command...command]
  2250.  
  2251.     If called without arguments, usage gives you a short information
  2252.     on the special characters used. Otherwise, usage shows you the
  2253.     usage of the given commands. Calling a command with a '?' as
  2254.     the only argument will show its usage, too.
  2255.  
  2256.     VERSION
  2257.  
  2258.     Usage    : version
  2259.  
  2260.     Show current version name, & authors.
  2261.  
  2262.     WAITFORPORT
  2263.  
  2264.     Usage    : waitforport portname [seconds]
  2265.     Example    : waitforport rexx_ced 5
  2266.  
  2267.     Waits for a port to come up. Default time is 10 seconds.
  2268.  
  2269.     WHEREIS
  2270.  
  2271.     Usage    : whereis [-r] filename [ device1...deviceN ]
  2272.  
  2273.  
  2274.     Options    :
  2275.      -r look on all drives.
  2276.  
  2277.     If just a file name is given, whereis searches all subdirectories of
  2278.     the current directory for that file. An asterisk '*' is appended to
  2279.     the file. Wild cards are allowed for the file (no asterisk will be
  2280.     appended then), but no path names. If additional arguments are
  2281.     given, whereis searches only these paths, not the current directory.
  2282.  
  2283.     WINDOW
  2284.  
  2285.     Usage    : window [-fblsaq] [dimensions]
  2286.  
  2287.     Options    :
  2288.         -f    (front) Window to front
  2289.         -b    (back)  Window to back
  2290.         -l    (large) Window to maximum size
  2291.         -s    (small) Window to minimum size
  2292.         -a    (activate)
  2293.         -q    (query) Lists screens and windows open
  2294.         -w    (width) Ignore window width for option "-q" (query)
  2295.  
  2296.     Various operations on CLI window. If dimensions are specified,
  2297.     they must be in the form x y width height, with values separated by
  2298.     spaces. Use dimension -1 for maximum value (eg, "window -1 -1 -1 -1"
  2299.     is equivalent to "window -l"), and -2 for keeping current value.
  2300.  
  2301.     The command "window -l" may be very useful on PAL machines to get
  2302.     a full PAL window from your login sequence, or if you use overscan
  2303.     WorkBench.
  2304.  
  2305.     Option -q gives, for each Screen and Window currently open,
  2306.     title, left edge, top edge, width, height, (depth).
  2307.  
  2308.     WRITEFILE
  2309.  
  2310.     Usage: writefile varname
  2311.  
  2312.     Writes a set of words to stdout, one word per line. Note that the
  2313.     name of the variable (var) must be supplied, not the value ($var).
  2314.  
  2315.  
  2316. IX. SPECIAL VARIABLES
  2317. ---------------------
  2318.  
  2319. There are a number variables, the write variable, that have a side effect on
  2320. your system (e.g.  changing the title bar), and some others, the read
  2321. variables, that tell you something about your environment (e.g.  the current
  2322. shell version).  You can also overlay the write variables with a local
  2323. variable, so any change only takes place while the current context is
  2324. valid.
  2325.  
  2326. LIST OF VARIABLES:
  2327. ------------------
  2328.  
  2329.     _abbrev
  2330.     Holds a number which lets you select the various modes of
  2331.     command-abbreviation:
  2332.  
  2333.       0   internal commands and commands buffered with "rehash"
  2334.           can no longer be abbreviated  (same as "unset _abbrev")
  2335.       1   internal commands can be abbreviated
  2336.       2   commands buffered with "rehash" can be abbreviated,
  2337.           the first (partially) matching command from the list is taken
  2338.       4   commands buffered with "rehash" can be abbreviated,
  2339.           if the command matches a buffered command completely,
  2340.           then this is taken, else the first partially matching
  2341.           command from the list is taken
  2342.       8   if command wasn't found in Cshell's internal program list
  2343.           (built with "rehash"), then search DOS path-list
  2344.  
  2345.     Numbers can be added to combine modes.
  2346.  
  2347.     The main difference between '2' and '4' is that '2' does not
  2348.     recognize a completely matching command if it has already
  2349.     found a partially matching command earlier in the list.  Eg,
  2350.     you type "ed" and you have (in this order) "EdPlayer" and
  2351.     "Ed" in your list, then "Ed" can never be called (except with
  2352.     absolute path). So '4' first seeks for a completely matching
  2353.     command -- and if it cannot find anything then (and only then)
  2354.     it searches for an abbreviated command.
  2355.  
  2356.     Thus it makes obviously no sense to use '2' and '4' together.
  2357.  
  2358.     By default, this variable is set to '5' (1+4).
  2359.  
  2360.     _bground
  2361.     True if the shell was started with a non-interactive input.
  2362.  
  2363.     _clinumber
  2364.     Contains the number (1-20) of current CLI.
  2365.  
  2366.     _clipri
  2367.     Task priority while editing command line.
  2368.     (also affects filename completion)
  2369.  
  2370.     _cquote
  2371.     If set to some value, quotation marks are handled as
  2372.     Commodore-Shell does, so that they are parsable by ReadArgs()
  2373.     (function call in dos.library). Commodore-Shell treats quotes
  2374.     within a string "as as". Only leading quotation marks "quote"
  2375.     other special chars (like spaces). In contrast to UNIX shells
  2376.     where quotation marks always "quote" other chars - regardless
  2377.     of their position. UNIX behavior (_cquote unset) is default.
  2378.  
  2379.     _cwd
  2380.     Holds a string representing the current directory we are in from
  2381.     root.  The SHELL can get confused as to its current directory if
  2382.     some external program changes the directory.  Use PWD to rebuild
  2383.     the _cwd variable in these cases.
  2384.  
  2385.     _debug
  2386.     Debug mode... use it if you dare.  must be set to some value
  2387.  
  2388.     _dirformat
  2389.     Holds a format string for option -z of builtin command "dir".
  2390.     Used to keep aliases short and to bypass problems with dir's
  2391.     format option "-z" (eg, it's not possible to specify other options
  2392.     after -z without using @pickargs/@pickopts).
  2393.  
  2394.     The format string is limited to a maximum of 80 characters.
  2395.  
  2396.     _every
  2397.     Contains the name of a command that is to be executed every time
  2398.     just before the prompt is printed. Do not use this to echo the
  2399.     prompt.
  2400.  
  2401.     _except
  2402.     See EXCEPTION
  2403.  
  2404.     _failat
  2405.     If a command returns with an error code higher than this, the
  2406.     batch file aborts. The default is 20.
  2407.  
  2408.     _hilite
  2409.     Holds the font attributes used for highlighting. One letter for one
  2410.     attribute:
  2411.       b    for bold
  2412.       i    for italic
  2413.       u    for underlined
  2414.       r    for reverse
  2415.       c3   for foreground color 3
  2416.       c3,2 for foreground color 3 and background color 2
  2417.     Any combinations are allowed. _hilite defaults to "c7", in terminal
  2418.     mode to "r".
  2419.  
  2420.     _history
  2421.     This variable is set to a numerical value, and specifies how far
  2422.     back your history should extend. Set it to 0 to disable history,
  2423.     for example if you test your programs for memory leaks. Defaults
  2424.     to 50.
  2425.  
  2426.     _insert
  2427.     Sets the default for insert/overtype mode for command line editing.
  2428.     ESC-i toggles between, but after <RET> the default is set back as
  2429.     indicated by this variable. By default _insert is 1, unsetting
  2430.     _insert will make overtype the default.
  2431.  
  2432.     _ioerr
  2433.     Contains the secondary error code for the last command. Will be
  2434.     changed after every external command and after a failed internal
  2435.     command. See @ioerr( )
  2436.  
  2437.     _kick
  2438.     holds version number of Operating System (version.library),
  2439.     eg, 37, 38, 39, 40, ...
  2440.  
  2441.     _kick2x
  2442.     True if exec.library V37+ could be opened
  2443.     (which means that kickstart 2.0 is around)
  2444.  
  2445.     _kick3x
  2446.     True if exec.library V39+ could be opened
  2447.     (which means that kickstart 3.0 is around)
  2448.  
  2449.     _lasterr
  2450.     Return code of last command executed.  This includes internal
  2451.     commands as well as external comands, so to use this variables
  2452.     you must check it IMMEDIATELY after the command in question.
  2453.  
  2454.     _lcd
  2455.     Holds the name of the last directory. The builtin alias 'dswap'
  2456.     cd's to that directory. If called again, you're back where you
  2457.     were.
  2458.  
  2459.     _man
  2460.     The path and name of your .doc files. Defaults to 'csh:csh.doc'
  2461.  
  2462.     _mappath
  2463.     Cshell allows invocation of foreign shells if a script starts with
  2464.     "#!" or ";!" followed by a command to execute.  To use unmodified
  2465.     Unix scripts pathname-mapping is necessary to convert pathes like
  2466.     "/usr/..." to, eg, "usr:...".  Set _mappath to enable this name-
  2467.     mapping.  By default _mappath is unset ("/usr/" would be inter-
  2468.     preted as relative AmigaDOS path).
  2469.  
  2470.     _maxerr
  2471.     The worst (highest) return value to date.  To use this, you usually
  2472.     set it to '0', then do some set of commands, then check it.
  2473.  
  2474.     _minrows
  2475.     Gives the minimum number of rows a window must have to turn on quick
  2476.     scrolling. Defaults to 34.
  2477.  
  2478.     _nobreak
  2479.     If set to some value, disables CTRL-C.
  2480.  
  2481.     _nomatch
  2482.     If set to some value, don't check patterns if they match.
  2483.     (By default CSH aborts command execution if all patterns does not
  2484.      match. If at least one pattern matches CSH does not abort.)
  2485.  
  2486.     _noreq
  2487.     If set to some value, disables system requesters ("Please insert
  2488.     volume ...."). Turned on in vt200 mode.
  2489.  
  2490.     _passed
  2491.     This variable contains the passed arguments when you SOURCE a file
  2492.     or execute a .sh file.  For instance:
  2493.  
  2494.     test a b c d
  2495.  
  2496.     -------- file test.sh ----------
  2497.     echo $_passed
  2498.     foreach i ( $_passed ) "echo YO $i"
  2499.     --------------------------------
  2500.  
  2501.     _path
  2502.     Tells CShell where to look for executable files. The current direc-
  2503.     tory and the AmigaDOS path will be searched first. The trailing
  2504.     slash for directories is not necessary any more.  The entire path
  2505.     will be searched first for the <command>, then for <command>.sh
  2506.     (automatic shell script sourcing). Example:
  2507.         set _path ram:c,ram:,sys:system,dh1:tools,df0:c
  2508.     (This path has the advantage that these directories need not even
  2509.      exist, that you can access devices (AmigaDOS path only knows
  2510.      volumes under Kick 1.3) and that no disk seeks happen at startup)
  2511.  
  2512.     The usage of _path is NOT recommended anymore, use the AmigaDOS
  2513.     search path instead (builtin command "path").
  2514.  
  2515.     _prghash
  2516.     The filename where the program hash list (command 'rehash')
  2517.     is loaded from and saved to.
  2518.  
  2519.     _prompt
  2520.     This variable now can contain the following control characters:
  2521.      %c  for color change. This highlights your prompt. See _hilite
  2522.      %e  for elapsed time. The time the last command took to execute.
  2523.      %m  for memory. This shows your current memory in K
  2524.      %t  for time. This shows your current time in the format HH:MM:SS
  2525.      %d  for date. This shows the current date in the format DD-MMM-YY
  2526.      %p  for path. This inserts the current path
  2527.      %V  for volume. This inserts the current volume
  2528.      %n  for number. This inserts the current process number
  2529.      %v  for version. This shows the version number of CShell
  2530.      %h  for history. This displays the current history number
  2531.      %f  for free store. This shows the free store on the current drive
  2532.      %r  for pRiority. Inserts the task priority of the current
  2533.      %s  for shells open. Inserts the result of 'howmany'
  2534.      %U  for user. Shows current user (only with "MultiUser" package)
  2535.      %x  for external cmd return code. Yields the last error code
  2536.     The default for prompt is now "%c%p> "
  2537.     The  if  command  will  set the prompt to a '_ ' if commands are
  2538.     disabled while waiting for a 'endif' or 'else' command (interactive
  2539.     mode only).
  2540.  
  2541.     _pipe
  2542.     The directory where temporaries are stored. Default: 'T:'
  2543.  
  2544.     _qcd
  2545.     Holds the name of the file where the all directories on your hard
  2546.     disk are stored. If not set, disables quick cd-ing.
  2547.  
  2548.     _rback
  2549.     Is the name of the command to be the prepended to the command line
  2550.     when '&' was added to it. Defaults to 'rback', can't be a multi
  2551.     word command yet.
  2552.  
  2553.     _rxpath
  2554.     The same as with _path, but this is where CShell looks for .rexx
  2555.     files. Defaults to REXX:
  2556.  
  2557.     _scroll
  2558.     Holds the number of lines to be scrolled at once when quick
  2559.     scrolling is used. If unset or <=1, quick scrolling is off.
  2560.     Defaults to 3.
  2561.  
  2562.     _terminal
  2563.     Indicates whether or not shell was started in terminal mode.
  2564.  
  2565.     _timeout
  2566.     Set the timeout period (in microsends) for the connected terminal to
  2567.     respond to a WINDOW STATUS REQUEST (special Amiga control sequence
  2568.     to get window bounds). Only used in terminal mode, of course.
  2569.  
  2570.     For local usage a small value is sufficient, for remote usage (eg,
  2571.     over a serial line) the value should be much higher (eg, 500000,
  2572.     which a 1/2 second).
  2573.  
  2574.     _titlebar
  2575.     The same control characters as for the _prompt can be used for
  2576.     _titlebar, too. The only difference is that %c is ignored. The
  2577.     titlebar is updated every time before the prompt appears.
  2578.  
  2579.     _verbose
  2580.     If set to 's', turns on verbose mode for source files (every command
  2581.     will be displayed before being executed). If set to 'a', displays
  2582.     all substeps while alias substitution. 'h' will hilight the debug
  2583.     output. Any combination allowed: set _verbose sah
  2584.  
  2585.     _version
  2586.     Contains the version number of the shell, e.g. 510.
  2587.  
  2588.  
  2589. X.   FUNCTIONS
  2590. --------------
  2591.  
  2592.     FUNCTIONS
  2593.     Functions are preceded by an @-sign and may not be abbreviated
  2594.     They must be preceded by a blank and a blank must follow the opening
  2595.     and precede the closing parenthesis. There must be no blank between
  2596.     the function name an the opening parenthesis. Example:
  2597.        echo @info( df0: )
  2598.     (NOTE: Later versions of Shell might allow that functions need not
  2599.            be at the beginning of an argument, so quote any @-signs not
  2600.            used for functions)
  2601.  
  2602.     Functions may be nested. The function names themselves are case
  2603.     sensitive, but the operations (like strcmp) aren't.
  2604.  
  2605.     Functions can be used as commands. They will echo their return value
  2606.     to stdout. Note that they can't be abbreviated and that the function
  2607.     list is searched after the command list. Example:
  2608.         drives          ---> DF0: DH1: DH2: RAM: WB_2.x:
  2609.     Therefore, functions can also be used like this:
  2610.         echo $(drives)
  2611.  
  2612.     So far, functions are not user definable.
  2613.  
  2614.     Note the difference between sets of words and strings. After
  2615.       set var hello world
  2616.     $var is a wordset, but after
  2617.       set var "hello world"
  2618.     var is one string. Although they look the same if echoed, they
  2619.     behave different, for example in 'foreach i ( var ) "echo hi'. The
  2620.     functions @split and @concat convert the two forms.
  2621.  
  2622.  
  2623. LIST OF FUNCTIONS:
  2624. ------------------
  2625.  
  2626.     @abbrev( str1 str2 [len] )
  2627.     true if the first <len> chars of str1 are an abbreviation of str2
  2628.     @abs( num )
  2629.     returns absolute value of <num>
  2630.     @age( file )
  2631.     the age of that file in days, null-string if file not found
  2632.     @age_mins()
  2633.     the age of that file in minutes, null-string if file not found
  2634.     @appsuff( name suffix )
  2635.     appends an suffix ( .ZOO ) to a string if it's not already there
  2636.     @arg( arg ... arg )
  2637.     see @pickargs( )
  2638.     @ask( title item ... item )
  2639.     asks for confirmation of every item and returns the confirmed ones
  2640.     (very similar to @confirm(), but default is negative)
  2641.     @availmem( [type] )
  2642.     returns free 'chip', 'fast' or otherwise total memory
  2643.     @basename( path ... path )
  2644.     returns the file name parts of the paths
  2645.     @center( word len )
  2646.     returns a string of length <len> with <word> centered in it
  2647.     @checkport( portname )
  2648.     indicates if given port exists
  2649.     @clinum( procname )
  2650.     returns the number of the cli identified by a name or a number
  2651.     @complete( abbrev word ... word )
  2652.     returns the first word <abbrev> is an abbreviation of
  2653.     @concat( word word ... word )
  2654.     concats all words in one blank separated string, see @split
  2655.     @confirm( title item ... item )
  2656.     asks for confirmation of every item and returns the confirmed ones
  2657.     (very similar to @ask(), but default is positive)
  2658.     @console( STDIN|STDOUT )
  2659.     tells whether stdin or stdout are interactive (not redirected)
  2660.     @dectohex( number )
  2661.     returns a string representing <number> in hex
  2662.     @delword( word word ... word n )
  2663.     returns a string with the n-th word deleted.
  2664.     @delwords( word word ... word n m )
  2665.     deletes the next m words from the n-th.
  2666.     @dirname( path )
  2667.     strips the base name from a path, just returns the directory
  2668.     @dirs( name name name name )
  2669.     returns the directories among the given file names, see @files
  2670.     @dirstr( lformat file )
  2671.     returns any info (size, date, file comment) about a file
  2672.     @drive( path )
  2673.     outputs the drive ( device ) name associated to <path>
  2674.     @drives( )
  2675.     outputs all available drives
  2676.     @exists( file )
  2677.     tells whether a file exists or not
  2678.     @fileblks( file file ... file )
  2679.     returns the # of blocks needed for the files, incl. dir blocks
  2680.     @filedate( file )
  2681.     returns a string representing the date of the given file
  2682.     @fileinfo
  2683.     Equivalent to @dirstr
  2684.     @filelen( file file ... file )
  2685.     count the total number of bytes of the given files
  2686.     @filenote( file )
  2687.     returns filenote of given file
  2688.     @fileprot( file )
  2689.     returns a string like ---arwed
  2690.     @filereq( title path&pattern filename )
  2691.     brings up the ASL file requester and returns the selected file name
  2692.     @files( file file ... file )
  2693.     gives you the files among those names, no directories. see @dirs
  2694.     @filesize
  2695.     Equivalent to @filelen
  2696.     @flines( varname )
  2697.     counts the number of lines in a readfile-file (faster than @words)
  2698.     @freebytes( path )
  2699.     the number of free bytes on the given path
  2700.     @freeblks( path )
  2701.     the number of free blocks on the given path
  2702.     @freestore( path )
  2703.     the amount of free store on that path, given in K, M and G
  2704.     @getenv( varname )
  2705.     returns the value of the named env: variable
  2706.     @getclass( file )
  2707.     returns the class (type) of the file. See chapter XIV
  2708.     @hextodec( hex-number )
  2709.     returns a string representing <hex-number> in dec
  2710.     @howmany( )
  2711.     indicates the # of shells running
  2712.     @index( string pattern )
  2713.     returns the index of pattern in string (starting at 1),
  2714.     0 if not found
  2715.     @info( path )
  2716.     the corresponding line from the 'info' command, each entry a word
  2717.     @intersect( word1 word2 word3 , word4 word5 word6 )
  2718.     returns all words which are in both lists. see @union, @member
  2719.     @ioerr( num )
  2720.     returns the corresponding error string to num
  2721.     @lookfor( file paths )
  2722.     looks for a file in the current directory and the paths. See $_path
  2723.     @lower
  2724.     lowercases its arguments. see @upper
  2725.     @match( word ... word "pattern" )
  2726.     returns the words in the list that match the DOS-pattern
  2727.     @max( num num ... num )
  2728.     computes the maximum of all given numbers
  2729.     @megs( number )
  2730.     expresses a number in K, M and G (-bytes), rounded correctly
  2731.     @member( word1 word word ... word )
  2732.     tells you if word1 is among the remaining words
  2733.     @min( num num ... num )
  2734.     computes the minimum of all given numbers
  2735.     @mix( arg1 ... argn )
  2736.     randomly mixes its arguments
  2737.     @mounted( device )
  2738.     returns a boolean indicating whether the specified device is mounted,
  2739.     (don't add an extra colon ':' at the end)
  2740.     @nameext( filename )
  2741.     returns all after the last dot of <filename>.
  2742.     @nameroot( filename )
  2743.     returns all before the LAST dot of <filename>.
  2744.     @opt( arg ... arg )
  2745.     see @pickopts( )
  2746.     @pathname( path )
  2747.     obsolete. use @dirname
  2748.     @pickargs( arg ... arg )
  2749.     picks of its arguments those which don't start with a '-'
  2750.     @pickopts( arg ... arg )
  2751.     picks of its arguments those which start which a '-'
  2752.     @rnd( seed )
  2753.     returns a 32 bit random number (default seed is 1);
  2754.     'seed' is optional and can be used to set new seed for @rnd( ),
  2755.     if you use seed=0 then CSH takes current system time as seed
  2756.     @rpn( expression )
  2757.     computes the rpn expression. See rpn command
  2758.     @scrheight( )
  2759.     outputs the current height of the screen the shell is running in
  2760.     @scrwidth( )
  2761.     outputs the current width of the screen the shell is running in
  2762.     @sortargs( name ... name )
  2763.     sorts its arguments alphabetically
  2764.     @sortnum( number ... number )
  2765.     sorts its arguments numerically
  2766.     @split( string )
  2767.     makes each blank separated part of @string a word, see @concat
  2768.     @strcmp( name name )
  2769.     returns -1, 0 or 1 depending of alphabetical comparison
  2770.     (case-sensitive)
  2771.     @stricmp( name name )
  2772.     returns -1, 0 or 1 depending of alphabetical comparison
  2773.     (case-insensitive)
  2774.     @strhead( breakchar string )
  2775.     see strhead command
  2776.     @strleft( string number )
  2777.     see strleft command
  2778.     @strmid( string n1 n2 )
  2779.     see strmid command
  2780.     @strright( string n )
  2781.     see strright command
  2782.     @strtail( breakchar string )
  2783.     see strtail command
  2784.     @subfile( varname n m )
  2785.     like @subwords, but acts on a readfile-file and is faster
  2786.     @subwords( word ... word n m )
  2787.     returns the next m words word of the given list starting from n
  2788.     @tackon( path file )
  2789.     see tackon command
  2790.     @trim( word word word )
  2791.     removes all leading and trailing blanks from the words
  2792.     @unique( word ... word )
  2793.     sorts the arguments and makes each of them unique
  2794.     @union( name ... name , name ... name )
  2795.     returns all names that are in either list. See @intersect, @member
  2796.     @upper( word ... word )
  2797.     upper cases the given words. see @lower
  2798.     @volume( path )
  2799.     returns the volume name in that path or ""
  2800.     @wincols( )
  2801.     returns the number of columns in the current shell window
  2802.     @winheight( )
  2803.     outputs the height of your window in pixels
  2804.     @winleft( )
  2805.     returns the left edge of your window
  2806.     @winrows( )
  2807.     returns the number of lines in the current shell window
  2808.     @wintop( )
  2809.     returns the top edge of your window
  2810.     @winwidth( )
  2811.     outputs the width of your window in pixels
  2812.     @without( name ... name , name ... name )
  2813.     returns all names of list 1 that are not in list 2
  2814.     @word( name ... name n )
  2815.     picks the n-th word from the list.
  2816.     @words( name ... name )
  2817.     returns the number of words in the list.
  2818.  
  2819.  
  2820. XI. MISCELLANEOUS
  2821. -----------------
  2822.  
  2823.     CShell now allows to do quick scrolling in large windows. Quick
  2824.     scrolling means that whenever the cursor reaches the bottom of
  2825.     the window, the text jumps up 3 or more lines at once. However,
  2826.     only the following commands support this:
  2827.         dir, cat, htype, strings, search, truncate, tee
  2828.     You can choose the number of lines to scroll at once by setting
  2829.     the variable _scroll. Unsetting it or setting it to a value <=1
  2830.     completely disables quick scrolling.
  2831.     You can also choose the number lines a window must at least have
  2832.     to turn on the quick scrolling by setting the _minrows variable.
  2833.     (Defaults to 34). Quick scrolling is automatically disabled when
  2834.     the command is redirected. By piping any command to cat, you can
  2835.     force it to quick scroll. Example:  List | cat
  2836.  
  2837.     CShell now can be terminated using the closing gadget in the
  2838.     AmigaDOS 2.0 shell window. Don't execute c:ENDCLI while using
  2839.     the shell. This can cause problems with external commands. The
  2840.     closing button provides a 'quit' command. You can define
  2841.       alias quit "Endcli;\\quit
  2842.     to assert that the CLI window closes when you click the button.
  2843.  
  2844.  
  2845.     EXCEPTIONS
  2846.     If  no  _except variable exists, any command which fails causes the
  2847.     rest of the line to abort as if an ABORTLINE had been executed.  If
  2848.     the _except variable exists, it is of the form:
  2849.  
  2850.     "nnn;commands..."
  2851.  
  2852.     where  nnn  is  some  value  representing  the  minimum return code
  2853.     required  to  cause  an  error.   Whenever a command returns a code
  2854.     which  is  larger  or  equal  to  nnn,  the commands in _except are
  2855.     executed  before  anything.   WHEN _except EXISTS, THE COMMAND LINE
  2856.     DOES  NOT  ABORT AUTOMATICALLY.  Thus, if you want the current line
  2857.     being executed to be aborted, the last command in _except should be
  2858.     an "abortline".
  2859.  
  2860.     Exception  handling  is  disabled  while  in the exception handling
  2861.     routine (thus you can't get into any infinite loops this way).
  2862.  
  2863.     Thus if _except = ";", return codes are completely ignored.
  2864.  
  2865.     Example:
  2866.  
  2867.     set _except "20;abortline"
  2868.  
  2869.  
  2870. XII. EXAMPLE SOURCE FILES
  2871. -------------------------
  2872.  
  2873. If from a CLI or the startup-script you say 'SHELL filename', that file is
  2874. sourced first.
  2875.  
  2876. ### compat.sh ###
  2877.  
  2878. # this makes sure that your old abbreviations don't call new commands
  2879.  
  2880. alias as  aset
  2881. alias cl  close
  2882. alias g   goto
  2883. alias h   help
  2884. alias he  help
  2885. alias m   md
  2886. alias q   quit
  2887. alias re  rename
  2888. alias w   window
  2889.  
  2890. alias kr  "rm -r ram:* >NIL:
  2891.  
  2892. ### End of compat.sh ###
  2893.  
  2894.  
  2895. Moreover, if you have a file called S:.cshrc, it will be sourced for every
  2896. Shell you run. This is useful for aliases and setting that you want in ALL
  2897. Shells.
  2898.  
  2899.  
  2900. ### Example S:.cshrc ###
  2901.  
  2902. Here is an example .cshrc file:
  2903.  
  2904. set F5 "cdir WORK:"^M
  2905. set f9 "ed s:login.sh"^M
  2906. set F9 "ed df0:s/startup-sequence"^M
  2907.  
  2908. alias toram  "%q foreach i ( $q ) \"cp -r $i: ram:$i >NIL:;assign $i: ram:$i
  2909. alias ramop  "md RAM:op; assign OP: ram:op
  2910. alias noop   "assign OP: ; rm -r ram:op
  2911. alias newop  "rm -r OP:*
  2912. alias dc     "dfc df0: to df1:
  2913. alias go     "%q assign WORK: Boot:$q; cd WORK:; source startme.sh
  2914. alias get    "%q cp $q RAM: >NIL:
  2915. alias filter "%a%b%c exec $b \\<$a \\>$c
  2916.     # reads $a, filters it with $b and writes result to $c
  2917.  
  2918. alias rm     "%q \\rm @confirm( Remove $q )
  2919. # or if you want a more safe one
  2920. alias qrm    "%q \\rm @ask( Remove $q )
  2921.  
  2922. #alias rm     "%a set f @pickargs( $a );set opts @pickargs( $a );\
  2923. # e -n OK to delete @words( @files( $f ) ) file(s) and @words( @dirs( $f ) )\
  2924. # directories\"? \";input b;if $b = y;\\rm $opts $f;endif
  2925. #        # for the anxious among us: confirmed rm
  2926.  
  2927. set _prompt   "%c%p> "
  2928.     # this puts the path highlighted in the prompt
  2929.  
  2930. # this one puts cli number, free mem, date and time in title bar
  2931. set _titlebar "Shell %n    Mem %m     Date %d    Time %t
  2932.  
  2933. # This file will be sourced for every Shell you start
  2934.  
  2935. ### End of example .cshrc ###
  2936.  
  2937. ****************************************************************************
  2938.  
  2939. If you are a CLI user, your startup-sequence may be as simple as:
  2940.  
  2941.     C:csh S:startup.sh
  2942.  
  2943. Here's a startup code:
  2944.  
  2945. ### Example S:startup.sh ###
  2946.  
  2947. wind -l    # if you are on a PAL machine, or use overscan
  2948.     # note that commands may be abbreviated (wind=window)
  2949.  
  2950. assign LC: Stuff:c  INCLUDE: Stuff:include   LIB: Boot:lib   QUAD: RAM:
  2951.  
  2952. rback C:FaccII; sleep 1
  2953.     # after spawning a process, it is always better to allow it
  2954.     # to load the command, to avoid excessive drive head movement
  2955.  
  2956. resident -d blink lc1 lc2 >NIL:    #defer loading
  2957.  
  2958. C:PopCli 300 C:Newcli         #using full pathname loads faster
  2959. C:FF -1 Siesta.font >NIL:
  2960. C:Patch_1 >NIL:
  2961. stack 8000            # lc1 and lc2 need this
  2962.  
  2963. source S:setdate.sh        # this is listed next
  2964.  
  2965. ### End of example startup.sh ###
  2966.  
  2967. ****************************************************************************
  2968.  
  2969. The following is an example source file to set date and time; it may be
  2970. used at startup if you don't have an internal clock.
  2971.  
  2972. ### setdate.sh ###
  2973.  
  2974. open CON:200/100/440/80/SetDate write 1
  2975. echo >.1 -n "Current date is "
  2976. date >.1
  2977. echo >.1 -n "Please enter date: "
  2978. input <.1 d
  2979. close 1
  2980. strlen len $d
  2981. if $len > 1 ; date $d ; endif
  2982. echo -n "New date: " ; date
  2983.  
  2984. ### End of setdate.sh ###
  2985.  
  2986. ***************************************************************************
  2987.  
  2988. Next comes a makefile that needs no Make program: may be executed from
  2989. Shell directly!!!
  2990.  
  2991. ### make.sh ###
  2992.  
  2993. if -t Shell.syms Shell.h; cc +HShell.syms Shell.h; rm shell.o; endif
  2994. if -t RAM:Shell.syms Shell.syms; cp -d Shell.syms RAM:; endif
  2995.  
  2996. foreach i ( main comm1 comm2 comm3 execom globals rawconsole run set \
  2997.  sub ) "if -t $i.o $i.c; echo Compile $i...;cc +IRAM:shell.syms $i.c; endif"
  2998.  
  2999. # we used line continuation for better visibility. this is not necessary,
  3000. # you can type it all in one line. no more limit of 256 bytes per line
  3001.  
  3002. if -t Shell run.o main.o comm1.o comm2.o comm3.o execom.o \
  3003. set.o sub.o globals.o rawconsole.o
  3004.     ln  +q -m -o Shell run.o main.o comm1.o comm2.o comm3.o\
  3005.     execom.o set.o sub.o globals.o rawconsole.o -la -lc
  3006. endif
  3007.  
  3008. ### End of make.sh ###
  3009.  
  3010.  
  3011. XIII.  DEFAULT VALUES
  3012. ---------------------
  3013.  
  3014. Some aliases are predefined whenever you start a new Shell. These are:
  3015.  
  3016.     CDIR
  3017.     Use "cdir directory" to clear the screen, set CD to directory,
  3018.     and list it.
  3019.  
  3020.     CLS
  3021.     Simply clear the screen.
  3022.  
  3023.     DSWAP
  3024.     Exchanges current and the previous current directory. For use in
  3025.     scripts as the symbol for last current directory may change.
  3026.  
  3027.     EXIT
  3028.     Leave Shell and exit CLI.
  3029.  
  3030.     MANLIST
  3031.     Display  a list of possible arguments to man.
  3032.  
  3033.     RX
  3034.     Executes a REXX script. Prevents unwanted starting of 'rxrec'.
  3035.  
  3036. Moreover, many variables have default values, and many function keys are
  3037. predefined. You can use set command to determine all of these.
  3038.  
  3039.  
  3040. XIV.  OBJECT ORIENTED FEATURES
  3041. ------------------------------
  3042.  
  3043. File classes are good for two things: Identifying files and command over-
  3044. loading. The latter means that the same command with files of different
  3045. type performs completely different actions.
  3046.  
  3047.     CLASSES OF FILES
  3048.  
  3049.     You can define a class of files using several 'class' commands.
  3050.     Here a simple example:
  3051.  
  3052.       class picture  suff=.pic suff=.iff suff=.ilbm
  3053.       class anim     suff=.anim
  3054.  
  3055.     From now on, everything with the suffix .pic, .iff or .ilbm will
  3056.     be identified as a picture. Please note that there may be no blanks
  3057.     between the names and the '=', and that blanks inside the names
  3058.     must be put in quotes. So these are the ways to identify a file:
  3059.  
  3060.       suff=.doc        True if the suffix of the file is .doc
  3061.       name=readme      True if the file is "readme"
  3062.       name="mod.*"     True if the name starts with 'mod.'
  3063.       offs=14,DC..C4FD True if the bytes starting at $14 are $DC,
  3064.                        anything, $C4, $FD  (all numbers hexadecimal!).
  3065.                        Each pair of dots means one byte ignored.
  3066.       chars            True if 90% of the bytes in the file are 32..127
  3067.                        or 9..13
  3068.       default          Always true, used to define the default type
  3069.  
  3070.     Note that only the first character is examined, so 's' = 'suff'.
  3071.     One class can be identified by more than one 'class' statement.
  3072.     They are looked at in the same sequence they were entered. So to
  3073.     make sure that an zoo archive misnamed as .lzh is identified
  3074.     correctly, use the following 'class' statements:
  3075.  
  3076.       class zoo offs=14,DCA7C4FD
  3077.       class lzh offs=2,2D6C68..2D
  3078.       class zoo suff=.zoo
  3079.       class lzh suff=.lzh
  3080.  
  3081.     Moreover, there is a builtin class 'dir', which means directory.
  3082.     Now we know many file types. But what to do with them? This is
  3083.     where we define 'actions'.
  3084.  
  3085.     ACTIONS ON CLASSES
  3086.  
  3087.     There may be one or more 'class' commands that define what actions
  3088.     need to be taken in various cases for that specific class:
  3089.  
  3090.       class zoo actions view="zoo -list" extr="zoo -extract"
  3091.       class lzh actions view="lz l"      extr="lz e"
  3092.  
  3093.     Whenever somebody tries to 'view' a test.zoo, the command
  3094.     'zoo -list test.zoo' will be issued, but if he tries to
  3095.     view test.lzh, then 'lz l test.lzh' will be executed. Note
  3096.     that any command supplied here goes through the normal csh
  3097.     parser, so AmigaDOS and csh paths will be searched. Aliases
  3098.     with arguments are allowed here, too, so whatever the user
  3099.     typed will be stored in the variable after the '%'.
  3100.  
  3101.     How do I tell a file that I want to 'view' it? There comes the
  3102.     second command used for object oriented features:
  3103.  
  3104.       action view test.zoo
  3105.  
  3106.     will first identify the type of that file and then apply, if
  3107.     possible, the 'view' action to it. Of course, this works best
  3108.     inside an alias:  alias v "action view" will define a v-command
  3109.     that views all types of files known to cshell. Similarly, you
  3110.     can define   alias xtr "action extr" and use this command to
  3111.     extract files from any type of archive.
  3112.     There is one action that will be sent to every file that you
  3113.     try to start but is not executable. This action is 'exec'.
  3114.     Assume you have defined the class 'picture', then after
  3115.  
  3116.       class picture actions view=Mostra exec=Mostra
  3117.  
  3118.     you can display a picture using Mostra by just typing its name.
  3119.     More builtin actions like 'rm' and 'dir' may be implemented,
  3120.     so don't use command names for action names.
  3121.  
  3122.     The batch file class.sh defines a few useful classes.
  3123.  
  3124.     SUPERCLASSES
  3125.  
  3126.     Assume you have a class for .c files, one for .h files, and
  3127.     one for .asm files. You might want to make the difference
  3128.     between them when identifying them, but in the end, they're
  3129.     all ASCII, aren't they? You can stat this with the command
  3130.  
  3131.       class c_source suff=.c is=ascii
  3132.  
  3133.     Now whenever an action on a file of the type c_source fails,
  3134.     the file is interpreted as of type ascii, and the same
  3135.     action is attemted again. This goes on until a class has no
  3136.     more superclass.
  3137.  
  3138.  
  3139. XV.     KEYMAPS
  3140. ---------------
  3141.  
  3142.     You define a keymap as a collection of key/function pairs. Both
  3143.     are given as numbers. There can be several keymaps which activate
  3144.     each other, but at first we only edit keymap 0, which is active
  3145.     at the beginning. All keys you define will eventually overwrite
  3146.     the old definitions in an existing keymap. Everything marked with
  3147.     a (*) is not yet implemented.
  3148.  
  3149.     KEYCODES
  3150.  
  3151.     1..255    The corresponding ASCII character
  3152.     256      Up Arrow
  3153.     257      Down Arrow
  3154.     258      Right Arrow
  3155.     259      Left Arrow
  3156.     260      Help
  3157.     261..270  F1..F10  (unshifted)
  3158.  
  3159.  
  3160.     Modifiers (add them to the key code)
  3161.  
  3162.     512       SHIFT (only necessary for arrows and fkeys)
  3163.     1024      ESC   (was pressed & released before this key)
  3164.  
  3165.     EDITFUNCTIONS
  3166.  
  3167.     - Movement      Move cursor...
  3168.      0  CursLeft    1 left
  3169.      1  CursRight   1 right
  3170.      2  WordLeft    1 word left
  3171.      3  WordRight   1 word right
  3172.      4  BegOfLine   to beginning of line
  3173.      5  EndOfLine   to end of line
  3174.  
  3175.     - Deleting      Delete...
  3176.     10  Backspace   char left from cursor
  3177.     11  Delete      char right from cursor
  3178.     12  BkspcWord   word left from cursor
  3179.     13  DelWord     word right from cursor
  3180.     14  DeleteToSOL to start of line
  3181.     15  DeleteToEOL to end of line
  3182.     16  DeleteLine  whole line
  3183.     17  DelScreen   whole screen and refresh current line
  3184.  
  3185.     - History insert
  3186.     20  Back        Move one line back in history
  3187.     21  Forward     Move one line forward in history
  3188.     22  Beg         Move to first line in history
  3189.     23  End         Move to last line in history
  3190.     24  Complete    History retrieve like '!'
  3191.     25  Exec        Execute history line & bring up next
  3192.     26  Tail        Insert previous line except first word
  3193.     27  Bottom      Go below last history command
  3194.     28  DupWord     Duplicates the last word on this line
  3195.     29  LastPrev    Insert last word of previous line
  3196.  
  3197.     - Completion
  3198.     30  Normal      Insert first matching file (or cycle)
  3199.     31  Partial     Insert common substring of all matching files
  3200.     32  All         Insert all matching files
  3201.     33  Directory   Find dir in quick cd list
  3202.     34  LastCD      Insert last current directory
  3203.     35  Show        Shows all matching files
  3204.     36  CompPrg1    Insert first matching program (or cycle)
  3205.     37  CompPrgAll  Shows all matching programs
  3206.  
  3207.     - Special
  3208.     40  Insert      Toggle Insert/Overwrite
  3209.     41  Quit        Silently perform 'quit'
  3210.     42  Help        Silently perform 'help'
  3211.     43  Refresh     Redraw current line
  3212.     44  Execute     Execute current line
  3213.     45  Leave       Edit new line, store this in hist
  3214.     46  EOF         Terminate shell
  3215.     47  NOP         Do nothing
  3216.     48  Echo^O      Echoes a ^O
  3217.     49  Beep        Echoes a ^G
  3218.  
  3219.     - Other
  3220.     50  Fkey        Execute command associated to last fkey
  3221.     51  Menu        Execute command associated to last menu
  3222.     52  Undo        Undoes last edit
  3223.     53  Repeat      Repeats last function
  3224.     54  SwapChar    Swaps the two chars left of cursor
  3225.     55  QuoteChar   Quote next char
  3226.  
  3227.  
  3228.     Command types
  3229.  
  3230.     0   +x      Editing function x, see above descriptions
  3231.     512 +x      Setmap x,     x=0..7
  3232.     1024+x      Insert key x, x=1..255
  3233.     1536+x      Macro x       x=1..15         (*)
  3234.     2048+x      String x      x=1..15         (*)
  3235.  
  3236.     Examples:
  3237.  
  3238.     keymap 0    66=49    # the  B key will beep
  3239.     keymap 0     2=16    # ^B key will erase line
  3240.     keymap 0  1122=35    # ESC-b will show matching files
  3241.     keymap 0 9=31 521=30 # Swaps TAB and SHIFT-TAB
  3242.  
  3243.     keymap 0 260=47      # do nothing on help
  3244.     keymap 0 12=17       # clear screen and refresh line on ^L
  3245.     keymap 0 18=29       # insert last word of prev line on ^R
  3246.  
  3247.  
  3248. XVI.    SCROLLING
  3249. -----------------
  3250.  
  3251. console.device
  3252. --------------
  3253.  
  3254. Ever wondered why Commodore's shell scroll a standard ASCII text file
  3255. very fast and why CSH scrolls (despite line-buffering in most commands)
  3256. the same text file at a noticable slower speed?
  3257.  
  3258. Now, first of all it must be said that CSH uses the same console
  3259. environment as Commodore's shell does.  So in fact both shells will
  3260. scroll at the SAME speed -- provided that they're configured in a
  3261. similar way.
  3262.  
  3263. Excerpt from "console" autodoc:
  3264.  
  3265. |     V39 console.device takes advantage of the ability to mask
  3266. |     bitplanes for faster scrolling, clearing, and rendering.
  3267. |     The actual number of bitplanes scrolled depends on which
  3268. |     colors you set via the SGR sequences.  For those using
  3269. |     the defaults of PEN color 1, and cell color 0, console.device
  3270. |     only needs to scroll 1 bitplane.  The actual number
  3271. |     of bitplanes scrolled is reset when ESCc is sent, and when
  3272. |     the console window is entirely cleared (e.g., FF).  In
  3273. |     general this should cause no compatability problems, unless
  3274. |     you are mixing console rendering with graphic.library calls
  3275. |     in the same portions of your window.  Console.device considers
  3276. |     the number of bitplanes it must scroll, and the screen display
  3277. |     depth so that interleaved bitplane scrolling can be taken
  3278. |     advantage of in cases where performance is not significantly
  3279. |     affected (interleaved scrolling, and masking are mutually
  3280. |     exclusive).  The determination of how many planes to scroll
  3281. |     is undefined, and may change in the future.
  3282.  
  3283. In other words:
  3284.  
  3285. After opening a window or sending ANSI sequences that clear the window
  3286. (ESC c, FF) the console.device checks how much bitplanes are in use.
  3287. The number of bitplanes depends on the number of colors used in this
  3288. window.
  3289.  
  3290. If there's only 1 color in use (this is default in Commodore's shell)
  3291. then console.device can perform very fast scrolling because only one
  3292. bitplane needs to be scrolled.
  3293.  
  3294. The scroll speed becomes slower the more colors you use.  Lots of
  3295. programs use at least one additional color by default.  This looks
  3296. nice but slows down scrolling.  Besides others, CSH is one of the
  3297. programs that make use of additional colors.  By default CSH has a
  3298. colored prompt.  And some internal commands like "dir" use a color
  3299. to highlight text.
  3300.  
  3301. With the variable "_hilite" you can control how CSH highlights text.
  3302. If you type "set _hilite b" then text will be highlighted by making
  3303. it bold.  See "man _hilite" for further information.
  3304.  
  3305. If you want really fast text scrolling then avoid using colors in text
  3306. output. For example, add "set _hilite b" in your "s:.cshrc" file.  And
  3307. configure other programs (like NewList, a very cool directory lister
  3308. by Phil Dietz) so that they don't use colored output.
  3309.  
  3310. If you have to use colored text (for any reason) then clear the window
  3311. as soon as possible to allow the console.device to re-enable fast text
  3312. scrolling.
  3313.  
  3314. ALWAYS REMEMBER:
  3315.  
  3316. To enable fast scrolling you must clear the screen (ESC c, FF) first.
  3317.  
  3318. As soon as you use more than one color in your text output,
  3319. console.device switches back to normal (slow) scrolling automatically.
  3320. Then you have to clear the screen manually to re-activate optimized
  3321. (fast) scrolling.
  3322.  
  3323.  
  3324. CpuBlit
  3325. -------
  3326.  
  3327. You're running CpuBlit and you wonder why under Kickstart 2.x text
  3328. scrolls faster than under Kickstart 3.x.
  3329.  
  3330. Check if you call CpuBlit with option "-b". This option MUST be set
  3331. to allow CpuBlit the handling of (so called) "broken" bitmaps.
  3332.  
  3333.