home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / hcshdemo.zip / csh-txt.zip / USERGUID.TXT < prev   
Text File  |  1993-10-04  |  705KB  |  21,873 lines

  1.                             
  2.                             
  3.                             
  4.                             
  5.                             
  6.                             
  7.                             
  8.                             
  9.                   Hamilton C shell(tm)
  10.  
  11.  
  12.  
  13.              User Guide and Reference Manual
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.                        Release 2.2
  26.  
  27.                       October, 1993
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.   Hamilton Laboratories, 13 Old Farm Road, Wayland, MA
  44.                        01778-3117
  45.         Phone 508-358-5715   +   FAX 508-358-1113
  46.     MCI Mail 389-0321   +   Internet 3890321@mcimail.com
  47.   BIX hamilton   +   CompuServe 70034,2025   +   Telex
  48.                        6503890321
  49.                             
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80. Copyright (c) 1988 - 1993 by Hamilton Laboratories.
  81.  
  82. All rights  reserved.  No part of this publication may be
  83. reproduced, stored in a retrieval system, or transmitted,
  84. in any  form or  by any  means,  electronic,  mechanical,
  85. photocopying, recording,  or otherwise  without the prior
  86. written permission  from Hamilton  Laboratories.  Printed
  87. in the United States of America.
  88.  
  89. AT,  PS/2   and  OS/2   are  registered   trademarks   of
  90. International Business  Machines Corporation.  Windows NT
  91. is a  trademark of  Microsoft Corporation.    UNIX  is  a
  92. registered  trademark   of  UNIX   System   Laboratories.
  93. Hamilton C shell is a trademark of Hamilton Laboratories.
  94.                
  95.  
  96.  
  97.  
  98.                                 Table of Contents
  99.  
  100.  
  101.  
  102.                  Preface .................................. v
  103.  
  104.                  License Agreement....................... vii
  105.  
  106.                  Introduction ............................. 1
  107.  
  108.                  Installation Guide ....................... 3
  109.                    Installation on OS/2   3
  110.                    Installation on Windows NT 15 
  111.  
  112.                  Common Problems ......................... 18
  113.  
  114.                  Product Support ......................... 29 
  115.  
  116.                  User Guide .............................. 32
  117.                    The Utilities    32 
  118.                    I/O Redirection and Piping  55
  119.                    The History Mechanism  66
  120.                    Variables    70
  121.                    Wildcarding  79
  122.                    Editing 87
  123.                    Quoting 92
  124.                    Expressions  96
  125.                    Aliases 105
  126.                    Programming Constructs      108
  127.                    Scheduling        130
  128.                    Order of Evaluation    137
  129.                    Customizing the Shell  140
  130.                    Summary 153
  131.  
  132.                  Examples ..............................  155
  133.                    Factor.csh   155
  134.                    Whereis.csh       156
  135.                    Samples Directory      157
  136.  
  137.                  Compatibility Guide ...................  162
  138.  
  139.                  Language Reference ....................  172
  140.                    Basic Statements  172
  141.                    Condition Testing      172
  142.                    Iteration    175
  143.                    Procedures   175
  144.                    Aliases 176
  145.                    Variable and Expression Manipulation  176
  146.                    Local Variables   178
  147.                    Function Keys     179
  148.  
  149.  
  150.  
  151.                                           iii
  152.  
  153.                    Miscellaneous Statements         181
  154.                    Statement Relationships     183
  155.                    I/O Redirection   183
  156.                    Expression Operators   185
  157.                    File System Tests 187
  158.                    Special Devices   188
  159.                    Wildcarding and Pattern Matching 190
  160.                    Filename Completion    192
  161.                    Command Line Editing   192
  162.                    History Recall    196
  163.                    Command Completion     196
  164.                    Quoting 198
  165.                    Escape Sequences  198
  166.                    Variable Substitution  200
  167.                    Substitution Modifiers 201
  168.                    Pathname Editing       203
  169.  
  170.                  Predefined Variables .................. 205
  171.                    Environmental Variables     205
  172.                    Process-Wide Variables 210
  173.                    Per-Thread Variables   212
  174.                    Variables, Sorted by Name   218
  175.  
  176.                  Built-in Procedures ................... 230
  177.  
  178.                  Utilities ............................. 235
  179.  
  180.                  Popular Aliases ....................... 242
  181.  
  182.                  Help Information ...................... 248
  183.                    Help for the shell          248
  184.                    Help for the utilities 250
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.                                           iv
  211.  
  212.                
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.             Preface
  223.  
  224.                Thank you  for purchasing  and using Hamilton C shell.
  225.             Our goal and guarantee is your satisfaction.
  226.  
  227.                Hamilton C  shell is  an advanced  command  processing
  228.             language for OS/2 and Windows NT.  It's a professionally-
  229.             oriented language  for manipulating  files, processes and
  230.             threads and  connections between  these objects.    As  a
  231.             language, it  offers  what  we  think  of  as  the  human
  232.             characteristics of  language:   a useful  vocabulary  and
  233.             grammar,  a  limitless  freedom  of  expression  and  the
  234.             ability to  describe and  relate events  in time.    Most
  235.             important, it  projects your influence into the future by
  236.             allowing you  to easily  describe you  want done  even if
  237.             what you  want is  quite complex  and dependent on future
  238.             events.
  239.  
  240.                Hamilton C  shell is  a full  implementation of  the C
  241.             shell language  popular on  engineering workstations.  It
  242.             was created  specifically for  OS/2  protected  mode  and
  243.             meticulously ported  to Windows  NT.  Not one of the more
  244.             than 105,000  lines of  code in  the current  release was
  245.             created on or ported from anything but OS/2 or NT.
  246.  
  247.                This product  complies with accepted standards for the
  248.             language and  with the conventions of OS/2 and NT.  Users
  249.             with previous  experience with  the standard  OS/2, NT or
  250.             DOS command  processors or  the  original  Unix  C  shell
  251.             should   find   enough   reasonably   familiar   language
  252.             constructs and  features to  make the product immediately
  253.             productive.
  254.  
  255.  
  256.  
  257.                                Douglas A. Hamilton
  258.                              Wayland, Massachusetts
  259.                                 December 9, 1988
  260.                          (Last revised October 4, 1993)
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.                                            v
  270.  
  271.                
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                                           vi
  329.  
  330. IMPORTANT -- READ CAREFULLY BEFORE OPENING.  By opening this
  331. sealed package, you indicate your acceptance of the following
  332. Hamilton Laboratories License Agreement.
  333.  
  334. Hamilton Laboratories License Agreement
  335.  
  336. This is a legal agreement between you, the end user, and Hamilton
  337. Laboratories.  By opening this sealed package, you are agreeing
  338. to be bound by the terms of this agreement.  If you do not agree
  339. to the terms of this agreement, promptly return the unopened
  340. package and any accompanying items for a full refund.
  341.  
  342.              HAMILTON LABORATORIES SOFTWARE LICENSE
  343.  
  344. 1.  GRANT OF LICENSE.  Hamilton Laboratories grants to you the
  345. right to use one copy of the enclosed Hamilton Laboratories
  346. software program (the ``SOFTWARE'') on a single terminal
  347. connected to a single computer (i.e., with a single CPU).  You
  348. may not network the SOFTWARE or otherwise use it on more than one
  349. computer or computer terminal at the same time.
  350.  
  351. 2.  COPYRIGHT.  The SOFTWARE is owned by Hamilton Laboratories or
  352. its suppliers and is protected by United States copyright laws
  353. and international treaty provisions.  Therefore, you must treat
  354. the SOFTWARE like any other copyrighted material (e.g., a book or
  355. musical recording) except that you may either (a) make a
  356. reasonable number of copies of the SOFTWARE solely for backup
  357. purposes or (b) transfer the SOFTWARE to a single hard disk
  358. provided the original and any other copies are kept solely for
  359. backup or archival purposes.  You may not copy the written
  360. materials accompanying the software.
  361.  
  362. 3.  OTHER RESTRICTIONS.  You may not rent or lease the SOFTWARE,
  363. but you may transfer the SOFTWARE and accompanying written
  364. materials on a permanent basis provided you retain no copies and
  365. the recipient agrees to the terms of this Agreement.  You may not
  366. reverse engineer, decompile or disassemble the SOFTWARE.  If
  367. SOFTWARE is an update, any transfer must include the update and
  368. all prior versions.
  369.  
  370. 4.  DUAL MEDIA SOFTWARE.  If this SOFTWARE package contains both
  371. 3 1/2'' and 5 1/4'' disks, you may use only the disks appropriate
  372. for your single-user computer.  You may not use the other disks
  373. on another computer or loan, rent, lease, or transfer them to
  374. another user except as part of the permanent transfer (as
  375. provided above) of all SOFTWARE and written materials.
  376.  
  377.                         LIMITED WARRANTY
  378.  
  379. LIMITED WARRANTY.  Hamilton Laboratories warrants that the
  380. SOFTWARE will perform substantially in accordance with the
  381. accompanying written materials for a period of 90 days from the
  382. date of purchase.  Some states do not allow limitations on the
  383. duration of an implied warranty, so the above may not apply to
  384. you.
  385. CUSTOMER REMEDIES.  Hamilton Laboratories' entire liability and
  386. your exclusive remedy shall be, at Hamilton Laboratories' option,
  387. either (a) return of the price paid or (b) repair or replacement
  388. of the SOFTWARE that does not meet this Limited Warranty and
  389. which is returned to Hamilton Laboratories with a copy of your
  390. receipt.  During the first 90 days from the date of purchase, if
  391. you determine that the SOFTWARE is unsatisfactory in any way, you
  392. may return it with proof of purchase and a written description of
  393. why the SOFTWARE was unsatisfactory for a full refund.
  394.  
  395. NO OTHER WARRANTIES.  Hamilton Laboratories disclaims all other
  396. warranties, either express or implied, including, but not limited
  397. to implied warranties of merchantability and fitness for a
  398. particular purpose, with respect to the SOFTWARE and accompanying
  399. written materials.  This limited warranty gives you specific
  400. legal rights.  You may have others, which vary from state to
  401. state.
  402.  
  403. NO LIABILITY FOR CONSEQUENTIAL DAMAGES.  In no event shall
  404. Hamilton Laboratories or its suppliers be liable for any damages
  405. whatsoever (including, without limitation, damages for loss of
  406. business profits, business interruption, loss of business
  407. information, or other pecuniary loss) arising out of the use of
  408. or inability to use this Hamilton Laboratories product, even if
  409. Hamilton Laboratories has been advised of the possibility of such
  410. damages.  Because some states do not allow the exclusion or
  411. limitation of liability for consequential or incidental damages,
  412. the above limitation may not apply to you.
  413.  
  414. This Agreement is governed by the laws of the State of
  415. Massachusetts.
  416.  
  417. Should you have any questions concerning this Agreement, or if
  418. you wish to contact Hamilton Laboratories for any reason, please
  419. write:  Hamilton Laboratories Customer Service, 13 Old Farm Road,
  420. Wayland, MA 01778-3117.
  421.  
  422.                                                                  Introduction
  423.  
  424.  
  425.             
  426.  
  427.  
  428.                               Hamilton C shell(tm)
  429.  
  430.  
  431.  
  432.  
  433.             Introduction
  434.  
  435.                Hamilton C shell is a language for interactively using
  436.             OS/2 and  Windows NT.   Compared to the standard OS/2 and
  437.             NT command  processors,  it  provides  a  vocabulary  and
  438.             grammar that  allows much  more complex  activities to be
  439.             described.  Some of its major innovations include
  440.  
  441.                +   Command line  editing of  enormous statements with
  442.                    arrow keys and filename and command completion.
  443.  
  444.                +   User-definable function keys.
  445.  
  446.                +   Fully  recursive   grammar.    Statements  can  be
  447.                    arbitrarily nested  or piped  without concern  for
  448.                    statement length or other arbitrary restrictions.
  449.  
  450.                +   Procedures and  aliases.   The vocabulary  of  the
  451.                    language is meant to be extensible by the user.
  452.  
  453.                +   Variables, arrays  and expressions.   Integer  and
  454.                    floating  point   arithmetic,   pattern   matching
  455.                    facilities  and  various  file  system  tests  and
  456.                    editing operators provide an expressive grammar.
  457.  
  458.                +   Threads  and   processes.     Child  threads   and
  459.                    processes  can   be  spawned   to   run   commands
  460.                    asynchronously or in the background.
  461.  
  462.                +   Command substitution.  The output  of one  command
  463.                    can  be  stuffed  back  on  the  command  line  as
  464.                    arguments to another.
  465.  
  466.                +   History.    Past  commands  can  be  recalled  and
  467.                    edited.
  468.  
  469.                +   Advanced filename wildcarding.
  470.  
  471.                This product  complies  fully  with  industry-accepted
  472.             definitions for  the C  shell language.   The user is not
  473.             asked to  learn yet  another new proprietary language not
  474.             available anywhere  else.    Instead,  a  tested,  proven
  475.             framework  has   been  adapted   with   modern   compiler
  476.             technology for OS/2 and NT:
  477.  
  478.  
  479.  
  480.  
  481.  
  482.                                       Page 1
  483.  
  484.      Introduction
  485.  
  486.  
  487.                1.  A  modern  top-down  parser  is  used  for  better
  488.                    language recognition and performance.
  489.  
  490.                2.  It's easier  to use.   The  syntax and grammar has
  491.                    been made  flexible and more consistent with other
  492.                    modern high level language conventions.
  493.  
  494.                3.  It knows  about OS/2 AND NT: HPFS, long filenames,
  495.                    environmental variables,  networks,  international
  496.                    character sets,  how to  start PM applications and
  497.                    (under OS/2  2.x) about  32-bit  and  Virtual  DOS
  498.                    machine (VDM) applications.
  499.  
  500.                4.  Threads   are    used   extensively   to   achieve
  501.                    performance  and  functionality  not  possible  in
  502.                    UNIX.
  503.  
  504.                5.  Feedback to  the user,  especially when  reporting
  505.                    errors has been improved.
  506.  
  507.  
  508.  
  509.             Who is it Designed For?
  510.  
  511.                Most  users   of  Hamilton   C  shell  are  relatively
  512.             technically oriented  computer  users.    Often,  they're
  513.             software developers.   They  have a  business need for an
  514.             OS/2 or an NT system.
  515.  
  516.                Peering over their shoulders, they typically have lots
  517.             of windows  open on  the screen.  Many of the windows are
  518.             running copies of this shell.  Some copies are transient,
  519.             created to  display with  little snippets  of information
  520.             needed on  the spur  of the  moment.  Other copies of the
  521.             shell would  be used for more long-running projects:  for
  522.             example, getting a make working for a major application.
  523.  
  524.                A shell  window is  like any  other application window
  525.             but with  a different  paradigm.   Instead of  data, rows
  526.             and columns of numbers or lines of text, the object being
  527.             manipulated is the machine itself.
  528.  
  529.                A good  shell tackles  a different  problem than icons
  530.             and windows.  Instead of the point-and-shoot immediacy of
  531.             ``do this single thing now,'' a shell offers language and
  532.             the ability  to describe  more customized  or  repetitive
  533.             actions, e.g.,  identify a suitable set of files, perform
  534.             some action  against them  and filter the results in some
  535.             interesting way.
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.                                       Page 2
  545.  
  546.                                                                  Installation
  547.  
  548.  
  549.             
  550.  
  551.  
  552.                                Installation Guide
  553.  
  554.  
  555.             This section outlines how to install the Hamilton C shell
  556.             on your  system.  If you are installing the OS/2 version,
  557.             follow the  instructions beginning  on  this  page.    To
  558.             install the  Windows NT  version  of  Hamilton  C  shell,
  559.             please turn to page 15.
  560.  
  561.             If  you   encounter  problems,   consult   the   ``Common
  562.             Problems'' section  on page  18 or  call us  for technical
  563.             support as described on page 29.
  564.  
  565.  
  566.  
  567.                               Installation on OS/2
  568.  
  569.  
  570.             The first  few steps, copying files from diskette to your
  571.             hard disk  and modifying your config.sys, are the same on
  572.             all releases  of OS/2.   The  remaining  steps  --  those
  573.             associated with  actually installing  Hamilton C shell on
  574.             your OS/2  desktop --  depend on  which release  of  OS/2
  575.             you're running.   We  suggest a  ``vanilla'' installation
  576.             initially, but later you may want to customize it to your
  577.             own tastes.   For  help with  that, read  the chapter  on
  578.             ``Customizing the Shell,'' beginnning on page 140.
  579.  
  580.             Once you've  gained familiarity  with both  OS/2 and with
  581.             the C  shell, you  may want  to set up the C shell as the
  582.             default command  processor for OS/2, completely replacing
  583.             cmd.exe as  described on  page 10.   The  advantage to be
  584.             gained (except under the 6.167 Beta and LA builds of 2.0)
  585.             is that  the C  shell will then be able to change its own
  586.             title bar and icon when you run an external command.
  587.  
  588.  
  589.  
  590.             System Requirements
  591.  
  592.             Installation requires  a 286-,  386- or  486-based AT+ or
  593.             PS/2+ or  compatible,  running  OS/2+  1.1  (Presentation
  594.             Manager) or  Microsoft SDK 1.06 or later.  Roughly 1.2 MB
  595.             of disk space is used.
  596.  
  597.             Hamilton C shell and the utilities supplied with it fully
  598.             support HPFS  and long  filenames when running under OS/2
  599.             1.2 or  later. They  will work properly in a Presentation
  600.             Manager text window or full-screen and with networks such
  601.             as LAN  Manager or  IBM LAN Server.  If you're using OS/2
  602.             2.x, it knows how to run 32-bit applications and start up
  603.  
  604.  
  605.  
  606.                                       Page 3
  607.  
  608.      Installation
  609.  
  610.  
  611.             Multiple Virtual DOS machines and run Win3.x applications
  612.             seamlessly on  the desktop.   The  product  is  not  copy
  613.             protected.
  614.  
  615.  
  616.  
  617.             Basic Installation, Part I  (All releases of OS/2)
  618.  
  619.             1.   Copy the  executables in  the bin directory into any
  620.                  desired directory on your search PATH, so long as it
  621.                  appears  ahead   of  the  directory  containing  the
  622.                  standard  IBM/Microsoft  more.com.    (We  supply  a
  623.                  dramatically improved  more.exe, which  should  take
  624.                  precedence.)   If you're  creating a  new directory,
  625.                  remember to add it to your search PATH in config.sys
  626.                  and in the login.csh file you create next.
  627.  
  628.             2.   Edit  config.sys,   adding  statements   to   define
  629.                  whatever directory  you choose  to designate as your
  630.                  HOME directory and to ensure you're configured for a
  631.                  sufficient number of threads.    The significance of
  632.                  a home  directory is  principally that  it  will  be
  633.                  convenient to  specify pathnames  relative  to  that
  634.                  directory.   The default  number of  threads is  too
  635.                  small if  you expect  to have  lots of windows open.
  636.                  Also, be  sure your PATH explicitly lists ``.'', the
  637.                  current directory.
  638.  
  639.                  You may  also want  to include  definitions for TABS
  640.                  and  COLORS.     more.exe  and  some  of  the  other
  641.                  utilities look  for TABS  to see if you want them to
  642.                  display text  with tabs  expanded out  to  something
  643.                  other than the default of every 8 characters.
  644.  
  645.                  By default, the C shell displays white characters on
  646.                  a black  background.   The COLORS  variable lets you
  647.                  choose something  different from  this set:   black,
  648.                  red, green,  yellow, blue,  magenta (or  blue  red),
  649.                  cyan (or  blue green)  and white.  Foreground colors
  650.                  may also  be bright,  dim, blink  or reverse.    The
  651.                  keyword ``on'' introduces background colors.  (Blink
  652.                  only causes  true blinking  full-screen; in  a  text
  653.                  window,  it  just  makes  the  background  brighter.
  654.                  Also, yellow  is a  true yellow only if it's bright.
  655.                  These are  OS/2 limitations  not related  to  the  C
  656.                  shell.)   For more  information  on  setting  screen
  657.                  colors, please refer to the customization chapter or
  658.                  to the colors.csh file in the samples directory.
  659.  
  660.                  Here's  an   example  of   what  you  might  add  to
  661.                  config.sys:
  662.  
  663.                       THREADS=255
  664.                       SET HOME=D:\DOUG
  665.  
  666.  
  667.  
  668.                                       Page 4
  669.  
  670.                                                                  Installation
  671.  
  672.  
  673.                       SET TABS=3
  674.                       SET COLORS=WHITE ON BLUE
  675.  
  676.                  (Please be  sure your  config.sys file contains only
  677.                  upper-case alphabetics,  no  lower-case,  if  you're
  678.                  using OS/2  1.1.   Lower-case alphabetics were known
  679.                  to cause random OS/2 system failures in that release
  680.                  of OS/2.   This  was a  known bug in the OS/2 kernel
  681.                  and was not application dependent.)
  682.  
  683.             3.   Copy  the   login.csh  and  startup.csh  files  into
  684.                  ``home'' directory.
  685.  
  686.                  Unless you're  convinced that  you've set  all  your
  687.                  environmental variables in your config.sys (and that
  688.                  your  PATH   explicitly  lists  ``.'',  the  current
  689.                  directory), use  the  dumpenv  utility  to  paste  a
  690.                  series of  setenv statements into the login.csh file
  691.                  to recreate  the environment  you've been using with
  692.                  cmd.exe:
  693.  
  694.                       dumpenv >>login.csh
  695.  
  696.                  (To see  what dumpenv  does, look at the source code
  697.                  in the  samples  directory  or  simply  run  dumpenv
  698.                  without redirecting the output.)
  699.  
  700.                  The login.csh  and startup.csh  files can  be edited
  701.                  with any ascii editor to customize the shell to your
  702.                  needs.   The login.csh file has a lot of comments in
  703.                  it which  can take  the shell  a second  or more  to
  704.                  read; you'll almost certainly want to delete some of
  705.                  them once  you've read  them so the shell will start
  706.                  up faster.   Also,  any setenv  statements that just
  707.                  duplicate  what's   in  your   config.sys   can   be
  708.                  discarded.
  709.  
  710.                  The remaining  steps depend on which release of OS/2
  711.                  you're running.
  712.  
  713.  
  714.  
  715.             Basic Installation, Part II  (OS/2 1.1)
  716.  
  717.             4.   Add csh.exe  with the  title ``Hamilton C shell'' to
  718.                  the ``Start  Programs'' menu.  To do this, pull-down
  719.                  ``Program'' and select ``Add...'' from the menu bar.
  720.                  Fill in:
  721.  
  722.                       Program title....   Hamilton C shell
  723.                       Path and file name  ....as
  724.                       appropriate....\csh.exe
  725.                       Parameters....      -L
  726.  
  727.  
  728.  
  729.  
  730.                                       Page 5
  731.  
  732.      Installation
  733.  
  734.  
  735.                  The ``-L'' part tells csh.exe when it starts up that
  736.                  it's a  ``login'' shell,  which means it should look
  737.                  for  a   login.csh  file.   (Refer to  page 248  for
  738.                  additional information on other options.)
  739.  
  740.             5.   You will  likely want  to create  a second entry for
  741.                  running full-screen.  It's more convenient if you're
  742.                  mostly working with applications that only run full-
  743.                  screen  or   if  you   want  faster   text  display,
  744.                  especially scrolling.   To do that, from the ``Start
  745.                  Programs'' menu,  pull-down ``Program''  and  select
  746.                  ``Copy...'' from the menu bar.  In the Copy Programs
  747.                  popup, fill  in the  following and push the ``Copy''
  748.                  button:
  749.  
  750.                       Change Title to:    Hamilton C shell -- Full
  751.                       Screen
  752.  
  753.                  Back in  the ``Start  Programs'' window,  select the
  754.                  new full  screen title,  pull-down  ``Program''  and
  755.                  select  ``Change...''.     In   the  Change  Program
  756.                  Information popup, push the ``Change'' button.  This
  757.                  brings up  the How  to Run the Program popup; select
  758.                  ``Run the program full-screen'' and ``Enter''.
  759.  
  760.             6.   All  the   material  in  the  samples  directory  is
  761.                  provided for  its tutorial value; you may or may not
  762.                  wish to copy it onto your hard disk.
  763.  
  764.             7.   Reboot your  system before starting Hamilton C shell
  765.                  for the  first time.  This causes the new statements
  766.                  in config.sys to take effect.
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.                                       Page 6
  793.  
  794.                                                                  Installation
  795.  
  796.  
  797.             Basic Installation, Part II  (OS/2 1.2 or 1.3)
  798.  
  799.             4.   Add csh.exe  with the  title ``Hamilton C shell'' to
  800.                  the ``Group  - Main''  menu.   To do this, pull-down
  801.                  ``Program'' and select ``New...'' from the menu bar.
  802.                  Fill in:
  803.  
  804.                       Program title:      Hamilton C shell
  805.                       Path and file name: ....as
  806.                       appropriate....\csh.exe
  807.                       Parameters:         -L
  808.  
  809.                  The ``-L'' part tells csh.exe when it starts up that
  810.                  it's a  ``login'' shell,  which means it should look
  811.                  for  a   login.csh  file.   (Refer  to page 248  for
  812.                  additional information on other options.)
  813.  
  814.             5.   You will  likely want  to create  a second entry for
  815.                  running full-screen.  It's more convenient if you're
  816.                  mostly working with applications that only run full-
  817.                  screen  or   if  you   want  faster   text  display,
  818.                  especially scrolling.   To do that, from the ``Group
  819.                  - Main''  menu,  pull-down  ``Program''  and  select
  820.                  ``Copy...'' from the menu bar.  In the Copy Programs
  821.                  popup, fill  in the  following and push the ``Copy''
  822.                  button:
  823.  
  824.                       Change Title to:    Hamilton C shell -- Full
  825.                       Screen
  826.  
  827.                  Back in  the ``Group - Main'' window, select the new
  828.                  full screen  title, pull-down ``Program'' and select
  829.                  ``Properties...'' .   In  the Properties popup, push
  830.                  the down arrow next to the ``Program Type:'' box and
  831.                  select ``OS/2  Full Screen''  on the  list that will
  832.                  appear and then push the ``Change'' button.
  833.  
  834.             6.   All  the   material  in  the  samples  directory  is
  835.                  provided for  its tutorial value; you may or may not
  836.                  wish to copy it onto your hard disk.
  837.  
  838.             7.   Reboot your  system before starting Hamilton C shell
  839.                  for the  first time.  This causes the new statements
  840.                  in config.sys to take effect.
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.                                       Page 7
  855.  
  856.      Installation
  857.  
  858.  
  859.             Basic Installation, Part II  (OS/2 2.x)
  860.  
  861.             4.   Open the  Templates folder and drag a program object
  862.                  to the  desktop (or  another folder) by pressing and
  863.                  holding the  right mouse button as you drag.  On the
  864.                  Program page  of the  ``Program -  Settings'' window
  865.                  that will appear, fill in:
  866.  
  867.                       Path and file name: ....as
  868.                       appropriate....\csh.exe
  869.                       Parameters:         -L
  870.  
  871.                  The ``-L'' part tells csh.exe when it starts up that
  872.                  it's a  ``login'' shell,  which means it should look
  873.                  for  a   login.csh  file.   (Refer  to  page 248 for
  874.                  additional information on other options.)
  875.  
  876.             5.   On  the  Window  page  of  the  Settings,  you  will
  877.                  probably want to set
  878.  
  879.                       Minimized button behavior:  Minimize window to
  880.                       desktop
  881.  
  882.                       Object open behavior:  Create new window
  883.  
  884.                  Doing this will let you conveniently open up lots of
  885.                  copies of the C shell as needed.
  886.  
  887.             6.   On the General page of the Settings, set
  888.  
  889.                       Title:              Hamilton C shell
  890.  
  891.                  Close the Settings by pressing Alt-F4.
  892.  
  893.             7.   You will  likely want  to create  a second entry for
  894.                  running full-screen.  It's more convenient if you're
  895.                  mostly working with applications that only run full-
  896.                  screen  or   if  you   want  faster   text  display,
  897.                  especially scrolling.   To do that, copy the C shell
  898.                  icon you  just created  by right-clicking  on it and
  899.                  selecting   ``Copy...''   and   then   choosing   an
  900.                  appropriate   destination   folder   (probably   the
  901.                  desktop) for  the copy.   You can also copy the icon
  902.                  by pressing  and holding the Ctrl key while dragging
  903.                  with the right mouse button.
  904.  
  905.             8.   Once you've  made the  copy, right-click  on it  and
  906.                  select ``Open''  and  then  ``Settings''.    On  the
  907.                  ``Session'' page, select ``OS/2 full screen''.  Then
  908.                  go to the ``General'' page and type a new title:
  909.  
  910.                       Title:              Hamilton C shell
  911.                                           Full Screen
  912.  
  913.  
  914.  
  915.  
  916.                                       Page 8
  917.  
  918.                                                                  Installation
  919.  
  920.  
  921.                  Close the  Settings window  for the copy by pressing
  922.                  Alt-F4.
  923.  
  924.             9.   All  the   material  in  the  samples  directory  is
  925.                  provided for  its tutorial value; you may or may not
  926.                  wish to copy it onto your hard disk.
  927.  
  928.             10.  Reboot your  system before starting Hamilton C shell
  929.                  for the  first time.  This causes the new statements
  930.                  in config.sys to take effect.
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.                                       Page 9
  979.  
  980.      Installation
  981.  
  982.  
  983.             Installation as the Default Command Processor
  984.  
  985.             The C  shell can also be installed as the default command
  986.             processor OS/2  protected mode,  meaning you  specify it,
  987.             not cmd.exe  in your config.sys.  The principal advantage
  988.             is that  when the  when the C shell is run as the default
  989.             command processor,  PM allows  the C  shell to change its
  990.             own title  bar and,  under OS/2  1.3 or  2.x (but not the
  991.             6.167 Beta  or LA builds), its own icon to show what it's
  992.             running.   This can  be quite helpful if you have lots of
  993.             copies of  the shell  running minimized and would like to
  994.             know what each one is doing.
  995.  
  996.             The disadvantage  is that  the installation  is  slightly
  997.             messy and it does disable cmd.exe's ability to change its
  998.             title bar  and icon.   For these reasons, most users will
  999.             want to  wait until  they've gained some familiarity with
  1000.             the C shell and with OS/2 before installing it this way.
  1001.  
  1002.             To install  the C shell as the default command processor,
  1003.             follow the  instructions for  the basic  installation but
  1004.             then make these changes, as appropriate for your system:
  1005.  
  1006.  
  1007.  
  1008.             Default Command Processor Installation Procedure  (OS/2
  1009.             1.2 or 1.3)
  1010.  
  1011.             1.   Edit  the   PROTSHELL  line   in  your   config.sys,
  1012.                  replacing  the   pathname  and  any  parameters  for
  1013.                  cmd.exe  (remembering   what  they  were)  with  the
  1014.                  pathname for the C shell and a -L (login) parameter.
  1015.                  The resulting line should look something like this:
  1016.  
  1017.                           PROTSHELL=C:\OS2\PMSHELL.EXE C:\OS2\OS2.INI
  1018.                               C:\OS2\OS2SYS.INI C:\OS2\BIN\CSH.EXE -L
  1019.  
  1020.             2.   Change the  pathname you  specify for the C shell in
  1021.                  Start Programs  or Group-Main  to *  (an  asterisk).
  1022.                  Also, change  the parameters line to be either blank
  1023.                  (1.1 or 1.2) or (1.3):
  1024.  
  1025.                       /K "%*"
  1026.  
  1027.             3.   Change the  entries (probably  named ``OS/2 Window''
  1028.                  or ``OS/2  Full Screen'')  in  Group-Main  or  Start
  1029.                  Programs  for   cmd.exe  to  fill  in  the  complete
  1030.                  pathname for  cmd.exe instead  of an  asterisk.  Set
  1031.                  the  parameters   to  whatever   you  had  specified
  1032.                  following the  pathname for cmd.exe (if anything) in
  1033.                  your config.sys before changing it in step 1.
  1034.  
  1035.             4.   Change any  entries in  any of  your program  groups
  1036.                  which invoke  .cmd scripts  to run  them via cmd.exe
  1037.  
  1038.  
  1039.  
  1040.                                      Page 10
  1041.  
  1042.                                                                  Installation
  1043.  
  1044.  
  1045.                  explicitly.   For example,  if you had an entry that
  1046.                  specified the  program ``c:\myapp\foo.cmd'',  change
  1047.                  that to:
  1048.  
  1049.                       Path and file name:  c:\os2\cmd.exe
  1050.                       Parameters: /C c:\myapp\foo.cmd ...any
  1051.                       additional parameters...
  1052.  
  1053.             5.   Reboot.
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.                                      Page 11
  1103.  
  1104.      Installation
  1105.  
  1106.  
  1107.             Default Command Processor Installation Procedure  (OS/2
  1108.             2.x)
  1109.  
  1110.             1.   Edit your  config.sys to  set OS2_SHELL  to point to
  1111.                  the C shell, specifying the -L (login) option, e.g.,
  1112.  
  1113.                       set  OS2_SHELL=c:\hamilton\bin\csh.exe -L
  1114.  
  1115.             2.   Modify the  Settings for  the OS/2  Window and  OS/2
  1116.                  Full Screen  icons to show the full path for cmd.exe
  1117.                  (e.g., ``c:\os2\cmd.exe'')  rather than  an asterisk
  1118.                  on the Program page.
  1119.  
  1120.             3.   Modify the  Settings for  the Hamilton C shell icons
  1121.                  to specify an asterisk pathname (meaning the default
  1122.                  shell),  deleting   any  mention   of  any   startup
  1123.                  parameters and  explicitly specifying  the  C  shell
  1124.                  icon rather than the default icon:
  1125.  
  1126.                  a.   Right-click on the icon and open the Settings.
  1127.  
  1128.                  b.   On the Program page, set
  1129.  
  1130.                       Path and file name: *
  1131.                       Parameters:
  1132.  
  1133.                  c.   Select ``Find...'' next to the icon display.
  1134.  
  1135.                  d.   Select ``Locate'' on the Find screen.
  1136.  
  1137.                  e.   Select the  ``Path'' page  on the Locate Folder
  1138.                       screen.
  1139.  
  1140.                  f.   Type the  pathname of  the directory containing
  1141.                       the  C  shell's  csh.ico  icon  file.    (E.g.,
  1142.                       ``c:\hamilton\bin''.)
  1143.  
  1144.                  g.   Press the  ``OK'' button  on the  Locate Folder
  1145.                       screen.
  1146.  
  1147.                  h.   Type ``csh.ico''  in the Name field on the Find
  1148.                       screen.
  1149.  
  1150.                  i.   Press the ``Find'' button.
  1151.  
  1152.                  j.   The Find  Results screen should appear with the
  1153.                       C shell  icon highlighted.   Press  the  ``OK''
  1154.                       button.
  1155.  
  1156.                  k.   Back in the General Settings screen, you should
  1157.                       now see  the C  shell's icon.   Press Alt-F4 to
  1158.                       close the screen.
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.                                      Page 12
  1165.  
  1166.                                                                  Installation
  1167.  
  1168.  
  1169.             4.   When you  reboot, the  C shell  will be  the default
  1170.                  shell and  it will appear with its correct icon both
  1171.                  for starting and when you minimize it.
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.                                      Page 13
  1227.  
  1228.      Installation
  1229.  
  1230.  
  1231.             
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.                                      Page 14
  1289.  
  1290.                                                                  Installation
  1291.  
  1292.  
  1293.             
  1294.  
  1295.  
  1296.                            Installation on Windows NT
  1297.  
  1298.  
  1299.             This section  describes how  to install  the  Windows  NT
  1300.             version of Hamilton C shell.
  1301.  
  1302.  
  1303.  
  1304.             System Requirements:
  1305.  
  1306.             Installation  requires  a  386-,  486-  or  Pentium-based
  1307.             machine for  the Intel  x86 version,  a  MIPS  R4000-  or
  1308.             R4400-based machine  for the  MIPS version or a DEC Alpha
  1309.             AXP-based machine  for the  Alpha version  of Hamilton  C
  1310.             shell.   The machine must be running the final release of
  1311.             Windows NT,  build 511  (on Intel or MIPS) or 528 (Alpha)
  1312.             or later.   Roughly  2.1 MB  of disk  space is used on an
  1313.             Intel machine, 3.5MB on a MIPS or 4.3MB on an Alpha.
  1314.  
  1315.  
  1316.  
  1317.             Basic Installation:
  1318.  
  1319.             1.   Copy the contents of the bin and samples directories
  1320.                  onto your hard disk, putting them anywhere you like.
  1321.                  (Notice that  the bin directory is too big to fit on
  1322.                  one diskette;  you'll have  to merge the two or more
  1323.                  diskettes, depending on which system you have.)
  1324.  
  1325.             2.   Copy the  login.csh and  startup.csh files  into any
  1326.                  directory you  care to  designate as  your  ``home''
  1327.                  directory.   The significance of a home directory is
  1328.                  principally that  it will  be convenient  to specify
  1329.                  pathnames relative to this directory.
  1330.  
  1331.             3.   Edit   the    login.csh   and   startup.csh   files,
  1332.                  customizing them  to meet your needs.  The login.csh
  1333.                  file has  a lot of comments in it which can take the
  1334.                  shell a  second or  more to read each time it starts
  1335.                  up; you'll  almost certainly  want to delete some of
  1336.                  these comments  once you've  read them  so the shell
  1337.                  will start up faster.
  1338.  
  1339.             4.   Edit  the   environment  variables  by  opening  the
  1340.                  Control Panel  and then,  within that,  opening  the
  1341.                  system icon.
  1342.  
  1343.                  To define a variable through the Control Panel, type
  1344.                  the variable  name in the ``Variable:'' fill-in box,
  1345.                  the value  in the  ``Value:'' box  and click  on the
  1346.                  ``Set'' button.
  1347.  
  1348.  
  1349.  
  1350.                                      Page 15
  1351.  
  1352.      Installation
  1353.  
  1354.  
  1355.                  a.   Create  or   edit  your   entry  for  the  PATH
  1356.                       variable, adding  the full  pathnames for the C
  1357.                       shell's bin  and  samples  directories  to  the
  1358.                       list.
  1359.  
  1360.                  b.   Create  an   entry  for  the  HOME  environment
  1361.                       variable,  setting   its  value   as  the  full
  1362.                       pathname of  the  directory  where  you  placed
  1363.                       login.csh and startup.csh.
  1364.  
  1365.                  c.   You may  also want  to include  definitions for
  1366.                       TABS  and  COLORS.    The  shell  and  all  the
  1367.                       utilities look for TABS to see if you want them
  1368.                       to display  text  with  tabs  expanded  out  to
  1369.                       something other  than the  default of  every  8
  1370.                       characters.
  1371.  
  1372.                       By  default,   the  C   shell  displays   white
  1373.                       characters on  a black  background.  The COLORS
  1374.                       variable lets  you choose  a  combination  from
  1375.                       this set:  black,  red,  green,  yellow,  blue,
  1376.                       magenta (or blue red), cyan (or blue green) and
  1377.                       white.   Foreground collows may also be bright,
  1378.                       dim, blink  or reverse.    The  keyword  ``on''
  1379.                       introduces  background  colors.    (Blink  only
  1380.                       causes true  blinking full-screen;  in  a  text
  1381.                       window, it  just makes the background brighter.
  1382.                       Also, yellow  is a  true yellow  only  if  it's
  1383.                       bright.    These  are  system  limitations  not
  1384.                       related to the C shell.)
  1385.  
  1386.                       Other color  settings you might want to specify
  1387.                       now or  at some  later time through the Control
  1388.                       Panel are  MOREPROMPT, MOREFILLIN and MOREERROR
  1389.                       (for customizing  the  more  utility's  command
  1390.                       line)  and   DELETIONS   and   ADDITIONS   (for
  1391.                       customizing the diff utility).
  1392.  
  1393.                       For more  information on setting screen colors,
  1394.                       please refer  to the the colors.csh file in the
  1395.                       samples  directory   or  to  the  Customization
  1396.                       chapter.
  1397.  
  1398.                  Here's an example of the settings you might specify:
  1399.  
  1400.                       HOME=d:\doug
  1401.                       PATH=d:\hamilton\bin;d:\hamilton;samples
  1402.                       COLORS=white on blue
  1403.                       TABS=3
  1404.                       ADDITIONS=bright white on green
  1405.                       DELETIONS=bright white on red
  1406.                       MOREPROMPT=red on white
  1407.                       MOREFILLIN=black
  1408.                       MOREERROR=bright white on red
  1409.  
  1410.  
  1411.  
  1412.                                      Page 16
  1413.  
  1414.                                                                  Installation
  1415.  
  1416.  
  1417.             5.   Add csh.exe  with the  title ``Hamilton C shell'' to
  1418.                  the Program Manager.  To do this, pull-down ``File''
  1419.                  and select  ``New''.    A  pop-up will appear asking
  1420.                  that you  confirm this  will be  a new Program Item.
  1421.                  On the next pop-up, fill in:
  1422.  
  1423.                       Description:        Hamilton C shell
  1424.                       Command Line:       ....as
  1425.                       appropriate....\csh.exe -L
  1426.  
  1427.                  The ``-L'' part tells csh.exe when it starts up that
  1428.                  it's a  ``login'' shell,  which means it should look
  1429.                  for a login.csh file.
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.  
  1466.  
  1467.  
  1468.  
  1469.  
  1470.  
  1471.  
  1472.  
  1473.  
  1474.                                      Page 17
  1475.  
  1476.      Common Problems
  1477.  
  1478.  
  1479.             
  1480.  
  1481.  
  1482.                                  Common Problems
  1483.  
  1484.  
  1485.  
  1486.  
  1487.             When I try to start the C shell in a new window, it dies
  1488.             and goes away before I can read its messages.
  1489.  
  1490.             You've probably  made an error on the ``Parameters'' line
  1491.             under OS/2  or in  the ``Command  Line'' under NT.  Under
  1492.             NT, select  the icon  for Hamilton C shell and press Alt-
  1493.             Enter to examine the properties.
  1494.  
  1495.             Under OS/2,  you can  force the  window will  to stay  up
  1496.             after the  shell exits  so you  can read  the message  by
  1497.             following the instructions appropriate for your system:
  1498.  
  1499.             OS/2 1.1:  Go to the ``How to Run the Program'' screen by
  1500.                  clicking on  the C shell entry in ``Start Programs''
  1501.                  and  pulling   down   ``Program''   then   selecting
  1502.                  ``Change...''.    Click  on  the  check  box  beside
  1503.                  ``Close the window...'' and press Enter.
  1504.  
  1505.             OS/2 1.2 or 1.3:  Click on the C shell entry in ``Group -
  1506.                  Main'',  pulling   down  ``Program''  and  selecting
  1507.                  ``Properties''.   Push the ``Options...'' button and
  1508.                  click on  the check  box next  to ``Close  window on
  1509.                  exit'', removing the X.
  1510.  
  1511.             OS/2 2.x:   Right-click  on the  icon and select ``Open''
  1512.                  followed by  ``Settings.''   On  the  Session  page,
  1513.                  click on  the check  box next  to ``Close  window on
  1514.                  exit'', removing the check.
  1515.  
  1516.  
  1517.  
  1518.             The shell doesn't know how to run an external command.
  1519.  
  1520.                One of the environmental variables, particularly HOME,
  1521.             PATH or  COMSPEC is  probably set  incorrectly.   Typical
  1522.             symptoms are  that the  shell doesn't seem to know how to
  1523.             find an  external command  or that it doesn't know how to
  1524.             run a .cmd file, etc.  Another variation might be that it
  1525.             runs the  old IBM  more.com rather than the new more.exe.
  1526.             If you  experience symptoms  like these, first check that
  1527.             these variables are set sensibly.
  1528.  
  1529.                The other  common possibility  under OS/2  1.x is that
  1530.             you're using  a network  and have  execute, but  not read
  1531.             access to the application you're trying to run.  Due to a
  1532.             bug in  the OS/2  1.x kernel,  the C shell cannot use the
  1533.  
  1534.  
  1535.  
  1536.                                      Page 18
  1537.  
  1538.                                                               Common Problems
  1539.  
  1540.  
  1541.             kernel's DosQAppType  function to  determine whether  the
  1542.             application should  be started  full-screen,  in  a  text
  1543.             window or  as a  PM graphics application.  Instead, the C
  1544.             shell is  forced to  read the  application's .exe  header
  1545.             itself; if  it can't  read it,  it can't  run  it.    The
  1546.             solution is to be sure you have read access.
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.  
  1594.  
  1595.  
  1596.  
  1597.  
  1598.                                      Page 19
  1599.  
  1600.      Common Problems
  1601.  
  1602.  
  1603.             The shell won't run my new program.
  1604.  
  1605.                Path hashing  can sometimes produce surprising results
  1606.             if you  create a  newer version in your current directory
  1607.             of a  command that already exists in another of your path
  1608.             directories.   The shell won't know you've done this; its
  1609.             hash will still only list the older version.  To overcome
  1610.             this problem, use either the rehash or unhash commands.
  1611.  
  1612.  
  1613.  
  1614.             The shell won't execute commands in the current
  1615.             directory.
  1616.  
  1617.                Your should  add the  current directory to the list of
  1618.             directories in  the PATH variable.  cmd.exe always checks
  1619.             the current  directory before  looking in any of the PATH
  1620.             directories.    Hamilton  C  shell  does  not  make  this
  1621.             assumption; if you want the current directory to be first
  1622.             one checked, you should specify it explicitly as ``.'' at
  1623.             the beginning of the list.  For example:
  1624.  
  1625.                  setenv PATH = '.;c:\os2;c:\os2\bin'
  1626.  
  1627.  
  1628.  
  1629.             The shell keeps running the old version my shell
  1630.             procedure.
  1631.  
  1632.                If you  define a  shell procedure  with proc in a .csh
  1633.             script file and then execute the script, the procedure is
  1634.             compiled into  an internal form that's much faster to run
  1635.             and it's  kept around  in memory  to make it run the next
  1636.             time even  faster.   If you change the text in the script
  1637.             file but  don't explicitly  throw away the old definition
  1638.             using unproc,  the C  shell won't  know it's  supposed to
  1639.             recompile.
  1640.  
  1641.  
  1642.  
  1643.             The shell won't run any cmd.exe internal commands.
  1644.  
  1645.                Most probably,  the  shell  is  unable  to  find  your
  1646.             startup.csh file  when it  starts up.   This  is the file
  1647.             that should  hold the aliases the shell uses to intercept
  1648.             cmd.exe's built-in commands.  Check to see that your HOME
  1649.             variable is  set to  the directory  where  you've  placed
  1650.             startup.csh and that your startup.csh file isn't garbled.
  1651.  
  1652.  
  1653.  
  1654.             When I start an application from the C shell, it dies
  1655.             immediately.
  1656.  
  1657.  
  1658.  
  1659.  
  1660.                                      Page 20
  1661.  
  1662.                                                               Common Problems
  1663.  
  1664.  
  1665.                Under OS/2,  if you  find  that  an  application  dies
  1666.             immediately after  starting, check  that the .exe file is
  1667.             properly marked with its type, i.e., full-screen, PM text
  1668.             windowable or  PM graphics.   The shell tries to start up
  1669.             an application in accordance with the way it's marked; if
  1670.             it's marked  wrong, the application just won't run.  Even
  1671.             very recently, a number of PM applications including even
  1672.             e.exe, the  System Editor,  were being  shipped unmarked,
  1673.             which by  convention is supposed to mean full-screen.  To
  1674.             look at  or change  how an application is marked, use the
  1675.             markexe.exe utility.  (Type ``markexe -h'' for help.)
  1676.  
  1677.                Another possibility  is that the application has a bug
  1678.             that makes  it fail  if the  maximum file handle count it
  1679.             inherits from  its parent  process is  greater  than  20.
  1680.             This problem  has been  seen in some past releases of the
  1681.             Microsoft linker  (discussed below)  and of  WordPerfect,
  1682.             for example.   You  can force the C shell not to bump the
  1683.             file limit when it starts up using the -Z option but this
  1684.             option only  works from the Start Programs (1.1) or Group
  1685.             (1.2) menus,  not from  the command  line.    (A  process
  1686.             always inherits  its initial  maximum file  handle  count
  1687.             from its parent; from there, a process can only raise its
  1688.             own limit, never lower it.)
  1689.  
  1690.  
  1691.  
  1692.             The Microsoft OS/2 linker fails under the C shell even
  1693.             though it works fine under cmd.exe.
  1694.  
  1695.                Microsoft has  determined  there  was  a  bug  in  the
  1696.             version of  the C  library used  to  build  the  link.exe
  1697.             distributed with  MS C  5.1.  The linker can fail if it's
  1698.             run as  a child  of a  process that  has a  maximum  file
  1699.             handle count  greater than  20; this is a problem because
  1700.             the  C  shell  sets  its  maximum  to  255.    If  you're
  1701.             encountering this  problem, try  patching  your  link.exe
  1702.             file with  the patchlnk.exe  utility.  (Type ``patchlnk -
  1703.             h'' for help.)
  1704.  
  1705.  
  1706.  
  1707.             When I try to run Microsoft's make.exe in the background
  1708.             it hangs.
  1709.  
  1710.                This is  a known  problem under  OS/2  with  make  and
  1711.             certain other  applications  that  need  to  spawn  child
  1712.             processes of  their own.  The OS/2 process initialization
  1713.             and completion logic requests a semaphore in KBDCALLS.DLL
  1714.             that's already  owned by  whatever process in that window
  1715.             is already  sleeping in  a KbdCharIn call.  Until another
  1716.             keystroke is  pressed, that  semaphore is  never released
  1717.             and the background processes are never allowed to cleanly
  1718.             exit.   This problem  has been  fixed  in  OS/2  2.x  and
  1719.  
  1720.  
  1721.  
  1722.                                      Page 21
  1723.  
  1724.      Common Problems
  1725.  
  1726.  
  1727.             through CSD  5050 for  OS/2 1.3  with a new KBDCALLS.DLL.
  1728.             That DLL  for 1.3  is available  on request from Hamilton
  1729.             Laboratories and can be downloaded from the listings area
  1730.             in the ``hamilton'' conference on BIX.
  1731.  
  1732.  
  1733.  
  1734.             copy or rename *.* doesn't work right.
  1735.  
  1736.                copy, xcopy,  rename and  del like  to  do  their  own
  1737.             wildcard expansion.   To make them work sensibly, be sure
  1738.             your startup.csh  file includes  and  that  you  use  the
  1739.             aliases and  procedure definitions we supply to intercept
  1740.             these commands  to turn  off shell  wildcarding just long
  1741.             enough to  run them.  These definitions can also serve as
  1742.             a model  if you  discover other applications that must do
  1743.             their own  wildcarding.   For more  information, refer to
  1744.             the discussion on page 23.
  1745.  
  1746.  
  1747.  
  1748.             The -! option doesn't work.
  1749.  
  1750.                The exclamation  point is  a special character for the
  1751.             shell.   The shell  lets you pick up text out of previous
  1752.             commands using  history references  that begin with ``!''
  1753.             followed  by   a  string  that  tells  what  text  you're
  1754.             retrieving.  To avoid having an exclamation confused as a
  1755.             history reference,  be sure the exclamation is at the end
  1756.             of a word, so the next character is a space or a tab.
  1757.  
  1758.  
  1759.  
  1760.             grep '^foo' doesn't work.
  1761.  
  1762.                The circumflex  has  special  meaning  as  the  escape
  1763.             character to  the C  shell, even  inside quotes.   If you
  1764.             want to  pass a  literal ``^'' to grep (or anything else)
  1765.             from the  command line,  you must  type ``^^'' unless the
  1766.             immediately preceding character was ``[''.
  1767.  
  1768.  
  1769.  
  1770.             When I list a directory over the network, not everything
  1771.             shows up.
  1772.  
  1773.                This is  a known  bug in the OS/2 networking code, not
  1774.             the C  shell.  The problem occurs if (1) the directory is
  1775.             read over a network, (2) directory entries are being read
  1776.             in blocks  (for higher performance) rather than one-at-a-
  1777.             time and  (3) the  total number  of characters in all the
  1778.             filenames in that directory happens to be just right.  In
  1779.             all cases  observed, adding  or  deleting  any  arbitrary
  1780.             entry in  the directory  makes the  problem go away.  The
  1781.  
  1782.  
  1783.  
  1784.                                      Page 22
  1785.  
  1786.                                                               Common Problems
  1787.  
  1788.  
  1789.             bug affects  the C  shell and  its utilities because they
  1790.             use blocked  reads; simpler  programs like  cmd.exe's DIR
  1791.             are unaffected because they read one entry at a time.
  1792.  
  1793.                The bug appears to have been introduced in IBM OS/2 EE
  1794.             CSD WR04098  and Microsoft  Lan Manager  2.0, both issued
  1795.             around year-end,  1990.  IBM has verified the problem and
  1796.             has developed  a fix,  which is  now shipping  as part of
  1797.             OS/2 EE  1.3.  If you encounter the problem and you're an
  1798.             IBM customer,  you should  call 1-800-237-5511 or contact
  1799.             your local  IBM representative  and ask for a copy of the
  1800.             new netwksta.sys  file being distributed as APAR IC02287.
  1801.             You can also download this file from the listings area of
  1802.             the ``hamilton''  vendor support  conference  on  Bix  or
  1803.             contact us directly and we'll mail you a copy.
  1804.  
  1805.                In the  meantime, this  release contains a work-around
  1806.             for disabling  the block  read feature.  If you create an
  1807.             environmental variable,  NETWORKBUG, and  set it equal to
  1808.             1, directory  reads  will  be  done  only  one-at-a-time,
  1809.             ensuring correct  results at  all times, albeit with some
  1810.             degradation in  performance.  You can do this either from
  1811.             the C shell:
  1812.  
  1813.                  setenv NETWORKBUG = 1
  1814.  
  1815.             or in your config.sys:
  1816.  
  1817.                  SET NETWORKBUG=1
  1818.  
  1819.  
  1820.  
  1821.             du, pwd and vol waste time sitting and spinning when they
  1822.             hit a removable drive that's empty.
  1823.  
  1824.                If you  have a removable media device other than A: or
  1825.             B:, these  utilities will  normally try  to report  them.
  1826.             That's probably  not you  want, at least not usually; you
  1827.             can specify  just the  set of drives you do want reported
  1828.             using the DRIVEMASK environmental variable.
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.                                      Page 23
  1847.  
  1848.      Common Problems
  1849.  
  1850.  
  1851.             cd /foo doesn't work.
  1852.  
  1853.                Hamilton C shell tries to serve users coming both UNIX
  1854.             and MS-DOS  backgrounds.  To do this, the C shell and all
  1855.             the utilities  accept command  line options to start with
  1856.             either ``-''  (UNIX-style) or ``/'' (DOS-style).  It also
  1857.             recognizes  filenames   typed  with   either  forward  or
  1858.             backward slashes.   But  when you  type  ``cd /foo'',  it
  1859.             guesses wrong  and thinks  you're trying  to  give  it  a
  1860.             command line option that it can't recognize.
  1861.  
  1862.                If this  is  really  not  what  you  intend,  set  the
  1863.             SWITCHCHARS environmental  variable to  just the specific
  1864.             characters you  want recognized.  E.g., you might include
  1865.             this in your config.sys to have only ``-'' recognized:
  1866.  
  1867.                  set SWITCHCHARS=-
  1868.  
  1869.  
  1870.  
  1871.             I've just installed OS/2 1.2 and suddenly my environment
  1872.             variables don't work.
  1873.  
  1874.                The auto  install program  distributed with  the fall,
  1875.             1989 releases  of OS/2  1.2 from  Microsoft and IBM has a
  1876.             bug.   It tries  to automatically  convert entries on the
  1877.             1.1 Start Programs menu into corresponding entries on the
  1878.             new 1.2  Group Main  menu.   If the  parameters line  for
  1879.             starting a  program has  text on  it (as  the  C  shell's
  1880.             does), the  entry is garbled even though it looks correct
  1881.             and causes  a garbled  environment to  be passed  to  the
  1882.             shell.   Editing the entry does not fix the problem.  The
  1883.             only solution  is to  delete the  entry and rekey it from
  1884.             scratch.
  1885.  
  1886.  
  1887.  
  1888.             I can't set my own screen colors.
  1889.  
  1890.                Yes, you  can (finally,  in this latest release.)  But
  1891.             you cannot  do it just by embedding ANSI escape sequences
  1892.             into your prompt since the C shell will immediately reset
  1893.             the colors back to what it thinks they should be.  To set
  1894.             your own  preferences for screen colors, you must use the
  1895.             COLORS  environmental  variable.    See  the  chapter  on
  1896.             customizing the  shell or  the colors.csh  script in  the
  1897.             samples directory for more information.
  1898.  
  1899.  
  1900.  
  1901.             The C shell's icon won't display in Group-Main.
  1902.  
  1903.                If you  install the  C shell  as the  default  command
  1904.             processor by  specifying it  on  the  PROTSHELL  line  in
  1905.  
  1906.  
  1907.  
  1908.                                      Page 24
  1909.  
  1910.                                                               Common Problems
  1911.  
  1912.  
  1913.             config.sys and  entering its path as ``*'' in Group-Main,
  1914.             you will  see only the default OS/2 icon in Group-Main if
  1915.             you select  View Icon.  If you start, then minimize the C
  1916.             shell, it  will have the correct icon, however.  This has
  1917.             been reported to IBM.  Their response is that, by design,
  1918.             when the  path is  an ``*,''  the  Group  code  does  not
  1919.             attempt to  resolve  the  actual  pathname  (and  whether
  1920.             there's any  icon associated  with it) until you actually
  1921.             click on  the entry  to start  it.  They agree this means
  1922.             you will  not see  the correct icon in the Group menu but
  1923.             claim this is what they intended and that it's not a bug.
  1924.  
  1925.  
  1926.  
  1927.             more crashes on the OS/2 2.0 Beta and LA Releases.
  1928.  
  1929.                The dynamic  link library  supporting 8514 displays in
  1930.             the beta  and LA releases from IBM has a bug which causes
  1931.             some VIO  applications, including  more, to  crash with a
  1932.             protection violation  if they're  run in  a text  window.
  1933.             They work  fine full-screen.  This problem has been fixed
  1934.             in the GA build.
  1935.  
  1936.  
  1937.  
  1938.             more hangs or exits prematurely on the OS/2 2.0 6.167 and
  1939.             LA releases.
  1940.  
  1941.                Under the  6.167 and  LA releases,  the  8514  display
  1942.             driver is  completely unusable.   It  even  has  problems
  1943.             repainting the  screen after  a menu  has been  closed or
  1944.             displaying icons in the templates folder.  It even causes
  1945.             more to hang the whole system if you have an 8514.
  1946.  
  1947.                But even using the VGA driver, random problems will be
  1948.             observed due, apparently, to bugs in the keyboard driver.
  1949.             Depending on  what's fed  to it through a pipe, more will
  1950.             occasionally prematurely  exit after the first screenful.
  1951.             All these problems have been fixed in the GA release.
  1952.  
  1953.  
  1954.  
  1955.             The C shell can't change its title bar or icon under the
  1956.             OS/2 2.0 6.167 Beta and LA releases.
  1957.  
  1958.                This functionality  was disabled in the 6.167 Beta and
  1959.             LA releases  as part  of the  work to  add the  Workplace
  1960.             Shell.  This problem has been fixed in the GA release.
  1961.  
  1962.  
  1963.  
  1964.             Alt-Enter doesn't work to grab commands from the history
  1965.             list under Windows NT and the OS/2 2.0 6.167 Beta
  1966.             Release.
  1967.  
  1968.  
  1969.  
  1970.                                      Page 25
  1971.  
  1972.      Common Problems
  1973.  
  1974.  
  1975.                Under Windows  NT and  OS/2 2.0  6.167,  Alt-Enter  is
  1976.             gobbled up  by the system as a keystroke combination used
  1977.             to signal  that an application should be toggled back and
  1978.             forth between  the desktop  and  a  full-screen  session.
  1979.             Under the  these systens, you'll have to type Ctrl-Shift-
  1980.             Enter instead.
  1981.  
  1982.  
  1983.  
  1984.             The C shell (and lots of other applications) only have
  1985.             default icons under the OS/2 2.0 6.167 Beta and LA
  1986.             Releases.
  1987.  
  1988.                The Workplace  Shell does not support .ico files.  All
  1989.             icons  for  text  applications  must  be  stored  in  the
  1990.             extended attributes.   The  latest builds  of the C shell
  1991.             have the  icon both  in the EA and in an .ico file but if
  1992.             you copied  the C  shell onto  your disk  with a  utility
  1993.             (e.g.., something  other than  cp) that  does not support
  1994.             EA's, that information probably got lost.
  1995.  
  1996.                To put  an icon  into the extended attributes, use the
  1997.             OS/2 1.3  File Manager,  selecting the file, pulling down
  1998.             ``Properties'' and selecting ``Icon...''.
  1999.  
  2000.  
  2001.  
  2002.             I just installed the C shell as the PROTSHELL and now
  2003.             when I start Commmunications Manager, it dies
  2004.             immediately.
  2005.  
  2006.                Communications Manager  is invoked  via a  .cmd script
  2007.             file.   Follow the  instructions in  step 4 on page 10 to
  2008.             rewrite that  entry to  start that  script explicitly via
  2009.             cmd.exe.
  2010.  
  2011.  
  2012.  
  2013.             I can't  wildcard filenames with $, quoted or escaped
  2014.             characters in them.
  2015.  
  2016.                Yes, you can (finally, in this latest release.)  To do
  2017.             so, just  quote or  escape the special characters.  E.g.,
  2018.             to get  all the  files that  begin with $, you might type
  2019.             ^$* or '$'* .
  2020.  
  2021.  
  2022.  
  2023.             I can't run the C shell inside an Epsilon editor window.
  2024.  
  2025.                The Epsilon  editor  tries  to  run  whatever  command
  2026.             processor you  use by  creating a full-screen session and
  2027.             doing a  KbdRegister to  intercept  the  KbdStringIn  API
  2028.             entry so  that Epsilon  can feed  it whatever you type in
  2029.  
  2030.  
  2031.  
  2032.                                      Page 26
  2033.  
  2034.                                                               Common Problems
  2035.  
  2036.  
  2037.             the editor  window.   Output (stdout and stderr) from the
  2038.             child session  is redirected  over a  pipe  back  to  the
  2039.             editor.
  2040.  
  2041.                There are  a couple  problems in  their approach:  (1)
  2042.             They neglected  to consider that not all applications use
  2043.             KbdStringIn; if  stdin is  attached to  a keyboard, the C
  2044.             shell reads  a keystroke  at a  time using  KbdCharIn and
  2045.             those calls still end up tied to that full-screen session
  2046.             rather than  being redirected.   (If stdin is attached to
  2047.             anything else,  it uses  DosRead calls.)   The authors of
  2048.             Epsilon really  should have  intercepted the whole set of
  2049.             Kbd  calls,   not  just   one  of  them.    (2)  Not  all
  2050.             applications write  their output  to  stdout  or  stderr;
  2051.             applications like  more, that  use Vio  output, won't run
  2052.             properly.   Their  output  appears  in  that  full-screen
  2053.             session, not  back in  the editor window.  Epsilon really
  2054.             should be  doing a  VioRegister to  grab the  Vio  output
  2055.             also.
  2056.  
  2057.                We are  working with  Lugaru Software  (the authors of
  2058.             Epsilon) on  a solution that should be available shortly.
  2059.             A partial workaround is to tell Epsilon to use a separate
  2060.             program, which  just reads  input and  pipes it  to the C
  2061.             shell.   Marty Klos  at IBM has written a small C program
  2062.             to do that and placed it in the public domain.  A copy is
  2063.             available on  request from  us or  may be downloaded from
  2064.             the listings  area of  the  ``hamilton''  vendor  support
  2065.             conference on BIX.
  2066.  
  2067.  
  2068.  
  2069.             rm doesn't remove anything, it just puts everything in a
  2070.             hidden directory.
  2071.  
  2072.                You're  using   the  notorious  Microsoft  rm  command
  2073.             instead of  the Hamilton  rm.   The Microsoft  rm doesn't
  2074.             remove anything;  it just  puts things in a hidden system
  2075.             directory.   Hamilton rm  is actually  in  hrm.exe  under
  2076.             Windows  NT   and  should   be  aliased  to  rm  in  your
  2077.             startup.csh file.   Fix  that and then, to get rid of all
  2078.             those ``deleted'' directories:
  2079.  
  2080.                  cd \; rm -x `ls -1ra +H | dim | grep 'deleted$'`
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.                                      Page 27
  2095.  
  2096.      Common Problems
  2097.  
  2098.  
  2099.             
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.  
  2120.  
  2121.  
  2122.  
  2123.  
  2124.  
  2125.  
  2126.  
  2127.  
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.                                      Page 28
  2157.  
  2158.                                                                       Support
  2159.  
  2160.  
  2161.             
  2162.  
  2163.  
  2164.                                  Product Support
  2165.  
  2166.  
  2167.                If you  encounter  problems  or  would  like  to  make
  2168.             suggestions for  a future  revision, please contact us by
  2169.             any of  the following  or by  regular mail;  we promise a
  2170.             prompt response.
  2171.  
  2172.                               Phone:     508-358-5715
  2173.                               FAX:       508-358-1113
  2174.                               MCI Mail:  389-0321
  2175.                               Telex:     6503890321
  2176.                               BIX:       hamilton
  2177.                               CompuServe: 70034,2025
  2178.                               Internet:  3890321@mcimail.com
  2179.  
  2180.                Also, on Bix, we have a vendor support conference.  Do
  2181.             a ``join  hamilton'' once  you get on or follow the menus
  2182.             into the conference system.
  2183.  
  2184.  
  2185.  
  2186.             Bug Reports
  2187.  
  2188.                If you  encounter what you believe to be a bug, please
  2189.             try to experiment to see what specific command or command
  2190.             sequence seems  to be  failing before calling.  A problem
  2191.             that's easily  reproducible is  obviously easier  to fix.
  2192.             Built in  to Hamilton C shell are a number of consistency
  2193.             checks to  trap bugs  before they  cause  damage  and  to
  2194.             snapshot enough  information  to  help  us  diagnose  and
  2195.             repair the  problem.   If the shell is actually crashing,
  2196.             look to  see if  a new  entry has been added to the error
  2197.             log, crash.csh,  in your home directory; that information
  2198.             will be useful.
  2199.  
  2200.                When you  call, we'll  try  to  provide  an  immediate
  2201.             workaround if  there is  one.   If the problem is serious
  2202.             but  straight-forwardly  correctable,  we  can  generally
  2203.             offer an  interim  release  at  no  charge  to  fix  that
  2204.             specific problem.   At the very least, we try to schedule
  2205.             it for an upcoming general release.
  2206.  
  2207.  
  2208.  
  2209.             Future Enhancements
  2210.  
  2211.                Work   continues    on   additional    features    and
  2212.             enhancements.   As they  become available, we want you to
  2213.             have them.
  2214.  
  2215.  
  2216.  
  2217.  
  2218.                                      Page 29
  2219.  
  2220.      Support
  2221.  
  2222.  
  2223.                Please return  the registration  form by  mail or FAX.
  2224.             Without that, we often have no way of knowing who you are
  2225.             to send  updates to.   This  is particularly true if your
  2226.             copy was  purchased  through  your  company's  purchasing
  2227.             department   or through  a retail  distributor.  Also, we
  2228.             look forward to your feedback as we strive to improve the
  2229.             product.
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.  
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.                                      Page 30
  2281.  
  2282.                                                                       Support
  2283.  
  2284.  
  2285.                
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.  
  2322.  
  2323.  
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.  
  2332.  
  2333.  
  2334.  
  2335.  
  2336.  
  2337.  
  2338.  
  2339.  
  2340.  
  2341.  
  2342.                                      Page 31
  2343.  
  2344.      Getting Started
  2345.  
  2346.  
  2347.             
  2348.  
  2349.  
  2350.                                    User Guide
  2351.  
  2352.  
  2353.  
  2354.  
  2355.             Getting Started
  2356.  
  2357.                Starting Hamilton  C shell  is simple:  select it from
  2358.             the Start Programs window or the Program Selector or type
  2359.             ``csh'' as  a command  to cmd.exe.    After  the  initial
  2360.             greeting, you'll  see the  first prompt:  (The underscore
  2361.             is meant to be the cursor.)
  2362.  
  2363.                  Hamilton C shell(tm) Release 2.2
  2364.                  Copyright (c) 1988-1993 by Hamilton Laboratories.
  2365.                  All rights reserved.
  2366.                  1 D% _
  2367.  
  2368.                This tells  you that it will remember what you type as
  2369.             command number  1 and  that your current drive is D.  The
  2370.             ``%'' is  traditional; rather  like the   ``>''  for DOS.
  2371.             Naturally, you  can change your prompt if you want, to be
  2372.             anything you  like.   For example,  to get  a prompt that
  2373.             looks like one you might get from cmd.exe+:
  2374.  
  2375.                  1 D% set prompt1 = '[$upper(cwd)] '
  2376.                  [D:\DOUG] _
  2377.  
  2378.                This works  by taking  the value  of the  cwd (current
  2379.             working directory)  variable, turning  it to  upper  case
  2380.             using one of the built-in procedures and pasting left and
  2381.             right brackets around it.  The value is recalculated each
  2382.             time a  prompt is  given, so it always displays an up-to-
  2383.             date value.   (Lists  of all  the built-in  variables and
  2384.             procedures are given in later sections.)
  2385.  
  2386.                To set it back:
  2387.  
  2388.                  [D:\DOUG] set prompt1 = '$@ $CDISK% '
  2389.                  3 D% _
  2390.  
  2391.  
  2392.  
  2393.             ____________________
  2394.             + We introduce  this is  as the  first example  with some
  2395.               trepidation:   the prompt  seems to  be the first thing
  2396.               people want  to change.   But it can also be one of the
  2397.               more daunting  projects   if  you're  getting  started.
  2398.               This example is offered more in the spirit of assurance
  2399.               that, with  a little  experience, the prompt can be set
  2400.               to anything you like.
  2401.  
  2402.  
  2403.  
  2404.                                      Page 32
  2405.  
  2406.                                                               Getting Started
  2407.  
  2408.  
  2409.             Basic Statements
  2410.  
  2411.                Generally speaking,  whatever commands  you might have
  2412.             typed into  cmd.exe  will  still  work  here.    Even  an
  2413.             ``internal'' cmd.exe function like dir works:
  2414.  
  2415.                  3 D% dir
  2416.                  
  2417.                   The volume label in drive D is USER.
  2418.                   Directory of D:\DOUG\SH\DOCS\SCRIPT\HELLO
  2419.                  
  2420.                  .            <DIR>      2-23-89   2:13p
  2421.                  ..           <DIR>      2-23-89   2:13p
  2422.                  HELLO    C         72   2-23-89  12:56p
  2423.                  HELLO    EXE     7731   2-23-89  12:57p
  2424.                  MEMOS        <DIR>      2-23-89   1:46p
  2425.                       5 File(s)   1581056 bytes free
  2426.                  4 D% _
  2427.  
  2428.                If the command you type refers to a .cmd batch file or
  2429.             a cmd.exe  internal function,  Hamilton C shell passes it
  2430.             to  a  child  process  running  cmd.exe  for  evaluation.
  2431.             (cmd.exe's  built-in   functions  are   intercepted  with
  2432.             aliases defined  in your  startup.csh file.)   Everything
  2433.             else is  evaluated directly  by Hamilton  C shell.    For
  2434.             example, if  you type  the name  of  an  .exe  file,  the
  2435.             appropriate DosExecPgm(  ) or  DosStartSession( ) call to
  2436.             the OS/2 kernel or CreateProcess( ) call to the NT kernel
  2437.             to start that program will be done directly by Hamilton C
  2438.             shell.
  2439.  
  2440.                A bit-mapped  hash mechanism  is used so that when you
  2441.             type the  name of a command, the shell zeroes right in on
  2442.             file you  mean.   It doesn't  have to  check  every  path
  2443.             directory for  every possible  extension.   Naturally, if
  2444.             you  type   a  command  that  doesn't  exist,  the  shell
  2445.             complains:
  2446.  
  2447.                  4 D% zork
  2448.                  csh:  Couldn't find an executable file named 'zork'.
  2449.  
  2450.                By being  more than  merely a  ``wrapper''  around  an
  2451.             existing  command   processor,  several   advantages  are
  2452.             created:     (1)  performance   is  understandably   (and
  2453.             visibly!) much higher and (2) limitations on command line
  2454.             lengths, etc.,  become the  relatively generous limits of
  2455.             OS/2 and  NT,  rather  than  the  restrictive  limits  of
  2456.             cmd.exe.
  2457.  
  2458.  
  2459.  
  2460.             Customizing the Screen Colors
  2461.  
  2462.  
  2463.  
  2464.  
  2465.  
  2466.                                      Page 33
  2467.  
  2468.      Getting Started
  2469.  
  2470.  
  2471.                The  C   shell's  default   screen  colors  are  white
  2472.             characters on a black background.  Highlighting and color
  2473.             are used  to make some things (special files, etc.) stand
  2474.             out.   All the use of color or highlighting is completely
  2475.             customizable.   You can  choose anything  you like.   The
  2476.             chapter on customization will go into this in detail, but
  2477.             for now, let's suppose we'd simply like to pick something
  2478.             a little  easier on  the eyes, like white characters on a
  2479.             blue background:
  2480.  
  2481.                  5 D% setenv COLORS = white on blue
  2482.  
  2483.  
  2484.  
  2485.             Command Line Editing
  2486.  
  2487.                With command  line editing,  you'll notice immediately
  2488.             how much  easier it is do things quickly without a lot of
  2489.             retyping.  As you try the examples, notice how the arrow,
  2490.             insert, delete,  home, end  and other keys can be used to
  2491.             recall previous  commands or make changes anywhere on the
  2492.             line.
  2493.  
  2494.                Command line  editing is  like  having  a  full-screen
  2495.             editor pasted  onto the  front end  of the  shell.    Key
  2496.             bindings are  intuitive and  follow accepted conventions.
  2497.             You can create enormous commands that stretch over screen
  2498.             after  screen  and  move  around  with  the  arrow  keys,
  2499.             inserting or  deleting anywhere.   Watch  changes  ripple
  2500.             almost instantly  down even  an entire screenful of text.
  2501.             We think you'll find our command line editing superior to
  2502.             anything you've seen or used elsewhere.
  2503.  
  2504.                The basic key assignments are:
  2505.  
  2506.                <Insert>       Toggle between insert and overstrike
  2507.                               modes.  (The cursor is thicker when
  2508.                               you're inserting.)
  2509.  
  2510.                <Home>   <End> Beginning/end of command line.
  2511.  
  2512.                <Left>   <Right> One character left/right.
  2513.  
  2514.                <Up>   <Down>  Up/down one command in the history
  2515.                               list.
  2516.  
  2517.                Pressing Ctrl  with the  arrow keys  lets you  move by
  2518.             words or  lines.   Pressing Alt instead does word or line
  2519.             deletion.   (The convention we follow is that the Alt key
  2520.             is a little ``more powerful'' than the Ctrl key.)
  2521.  
  2522.                What you  last deleted  is kept  in a scrap buffer and
  2523.             can be  pasted back  elsewhere.   To paste something from
  2524.  
  2525.  
  2526.  
  2527.  
  2528.                                      Page 34
  2529.  
  2530.                                                               Getting Started
  2531.  
  2532.  
  2533.             the scrap  buffer back  into the  command line,  move the
  2534.             cursor to where you want it done and press:
  2535.  
  2536.                Ctrl-<Insert>  Paste one word at a time.
  2537.  
  2538.                Alt-<Insert>   Paste the whole thing.
  2539.  
  2540.  
  2541.  
  2542.             Command Completion
  2543.  
  2544.                In  addition  to  backing  up  through  your  previous
  2545.             commands one at a time with ¡ and », you can also ask the
  2546.             shell to search back through any previous commands you've
  2547.             typed for  the last  command that  either started with or
  2548.             contained the characters in the previous word.
  2549.  
  2550.                Ctrl-<Enter>   means ``look for a command that started
  2551.                               with ...,'' and
  2552.  
  2553.                Alt-<Enter>    (again, a little ``stronger'') means
  2554.                               ``look for a command that contained the
  2555.                               string anywhere.''  (On NT, it's
  2556.                               necessary to type Ctrl-Shift-<Enter>
  2557.                               because Alt-<Enter> is grabbed by the
  2558.                               system to mean switch to full-screen.)
  2559.  
  2560.                Repeatedly pressing  these keys  cycles up through all
  2561.             the matching  commands you've  previously typed.  Command
  2562.             completion uses something called the history mechanism to
  2563.             recall commands  you've previously  typed.   Later, we'll
  2564.             devote a  whole chapter to some of the more advanced uses
  2565.             of history.
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.  
  2582.  
  2583.  
  2584.  
  2585.  
  2586.  
  2587.  
  2588.  
  2589.  
  2590.                                      Page 35
  2591.  
  2592.      Getting Started
  2593.  
  2594.  
  2595.             Filename Completion
  2596.  
  2597.                Filename completion  is another  ``creature comfort:''
  2598.             you type  just a fragment of a filename and let the shell
  2599.             fill in the rest.  The two variations are using the F key
  2600.             for basic  filename completion  or the  D key if you want
  2601.             all the duplicates listed.
  2602.  
  2603.                Alt-F or Ctrl-F  Filename completion.
  2604.  
  2605.                               Look for a filename that starts with
  2606.                               preceding characters.  If it matches a
  2607.                               single file, fill in the rest of the
  2608.                               name.
  2609.  
  2610.                               If more than one file matched, show the
  2611.                               part that was the same for all,
  2612.                               highlighted in green.  (Bright red
  2613.                               means there were no matches at all.)
  2614.  
  2615.                Alt-D or Ctrl-D  Duplicate completions.
  2616.  
  2617.                               Show any/all matching filenames, one
  2618.                               after the other with spaces between.
  2619.  
  2620.                Filename completion is actually done with wildcarding.
  2621.             Unlike cmd.exe,  Hamilton C  shell does  any  wildcarding
  2622.             before excuting the command you type.  It uses a powerful
  2623.             recursive  pattern   match  algorithm   that   guarantees
  2624.             sensible matches even if you type a very complex pattern.
  2625.             Wildcarding is the subject of a whole chapter up ahead.
  2626.  
  2627.  
  2628.  
  2629.             The Tour Begins Here
  2630.  
  2631.                The   following   chapters   introduce   the   various
  2632.             facilities Hamilton  C shell provides, starting with some
  2633.             of its  basic vocabulary:  the simple utilities that come
  2634.             with it.
  2635.  
  2636.                Following discussion shifts to the intrinsic, internal
  2637.             functions provided by the shell itself:  i/o redirection,
  2638.             pipes and command substitution; the history mechanism and
  2639.             wildcarding.
  2640.  
  2641.                Intermediate  level   discussion  follows,  describing
  2642.             expressions, variables  and aliases  and the  editing and
  2643.             quoting facilities.   The  process and  thread scheduling
  2644.             mechanism is  described, outlining how an activity can be
  2645.             placed in the background.
  2646.  
  2647.                The tour will then cross the threshold from discussion
  2648.             of individual  statements to  discussion of structures of
  2649.  
  2650.  
  2651.  
  2652.                                      Page 36
  2653.  
  2654.                                                               Getting Started
  2655.  
  2656.  
  2657.             statements.   Structures  for  iteration  and  condition-
  2658.             testing and procedural abstraction will be introduced.
  2659.  
  2660.                Finally, we'll  wrap up  with  discussion  of  how  to
  2661.             customize the  shell together  with a  section  detailing
  2662.             specific compatibility  issues between  the Hamilton  and
  2663.             original Berkeley C shells.
  2664.  
  2665.  
  2666.  
  2667.  
  2668.  
  2669.  
  2670.  
  2671.  
  2672.  
  2673.  
  2674.  
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.  
  2714.                                      Page 37
  2715.  
  2716.      Utilities
  2717.  
  2718.  
  2719.             
  2720.  
  2721.  
  2722.                                   The Utilities
  2723.  
  2724.  
  2725.                Hamilton C  shell comes  with a  lot of utilities that
  2726.             form some  of its  vocabulary.   They do  small, but oft-
  2727.             needed functions,  often  in  a  novel,  faster  or  more
  2728.             convenient way  than you'd find in ``plain vanilla'' OS/2
  2729.             or NT.   This  section provides  a quick  tour, outlining
  2730.             some of the capabilities and conventions.
  2731.  
  2732.  
  2733.  
  2734.             ls:  List files
  2735.  
  2736.                ls is a somewhat nicer way to list a directory:
  2737.  
  2738.                  6 D% ls
  2739.                  memos      hello.c    hello.exe  sysstuff
  2740.  
  2741.             Subdirectories are  highlighted (shown here in bold.)  If
  2742.             a file  or directory  has the  system bit set, it's still
  2743.             listed, displayed  in  green  (shown  here  in  italic.)+
  2744.             Normally, ls  lists everything  in lower  case for better
  2745.             readability.  In long format:
  2746.  
  2747.                  7 D% ls -l
  2748.                  D----  Feb 23  13:46          -  memos
  2749.                  ---A-  Feb 23  12:56         72  hello.c
  2750.                  ---A-  Feb 23  12:57       7731  hello.exe
  2751.                  -S-A-  Feb 23  13:22         15  sysstuff
  2752.  
  2753.                Conventionally, ls  lists things  alphabetically, with
  2754.             directories ahead  of files.  There might be hidden files
  2755.             or directories, but to see them you have to ask:
  2756.  
  2757.                  8 D% ls +H
  2758.                  memos      hello.c    hello.exe  hiding     sysstuff
  2759.  
  2760.  
  2761.  
  2762.             Conventions
  2763.  
  2764.                To find  out how  any of  the utilities work, just use
  2765.             the -h option.  For example,
  2766.  
  2767.                  9 D% ls -h
  2768.             ____________________
  2769.             + All our  examples will be given in terms of the default
  2770.               screen colors.   But  these are  easily changed to your
  2771.               own preferences.   See  the chapter on customization or
  2772.               the colors.csh script file in the samples directory.
  2773.  
  2774.  
  2775.  
  2776.                                      Page 38
  2777.  
  2778.                                                                     Utilities
  2779.  
  2780.  
  2781.             tells about  options for  more detailed listings, sorting
  2782.             the list by date or by size, selecting only certain types
  2783.             of files,  etc.   ls is  a read-only  activity; it  never
  2784.             makes any  changes to  the file system.  Lists are always
  2785.             sorted in  memory; its  speed and  flexibility completely
  2786.             obsolete  the  old  (and  dangerous)  ``directory  sort''
  2787.             utilities popular on DOS.
  2788.  
  2789.                The  names   of  the   utilities  were  chosen  to  be
  2790.             consistent with  the names  of similar functions on UNIX,
  2791.             where they  provided  much  of  the  vocabularly  of  the
  2792.             original UNIX  C shell.   But  changing  the  name  of  a
  2793.             utility  is   a  simple   matter:     just   rename   the
  2794.             corresponding .exe file or, better still, create an alias
  2795.             (discussed later.)
  2796.  
  2797.                By convention,  the utilities  expect options  to come
  2798.             ahead of  any files  you  specify.    Options  are  case-
  2799.             sensitive.   We've tried  to use  mneumonic  letters  for
  2800.             options (e.g.,  h for help) and to use the same letter to
  2801.             mean the  same thing  across related utilities; achieving
  2802.             that is  simply  more  feasible  with  52,  not  just  26
  2803.             characters to choose from.
  2804.  
  2805.                Our examples  generally show  options introduced  with
  2806.             ``-'', but  you could  equally well  follow the DOS-style
  2807.             convention of  using ``/''  if you prefer.  If indeed you
  2808.             want only  ``-'' or  only ``/''  interpreted as an option
  2809.             character,  this   can  be   set  with   the  SWITCHCHARS
  2810.             environmental variable,  which can be set either from the
  2811.             C shell  or from your config.sys file on OS/2 or from the
  2812.             Control Panel  on NT.  Sadly, it won't have any effect on
  2813.             the standard  OS/2 or NT commands like dir or xcopy or on
  2814.             applications you  purchase elsewhere, but it will work on
  2815.             all the commands supplied with the C shell.  For example,
  2816.             to have only ``-'' recognized as an option character, you
  2817.             might type this into the C shell:
  2818.  
  2819.                  10 D% setenv SWITCHCHARS = -
  2820.  
  2821.             or put  this into  config.sys (rebooting  to make it take
  2822.             effect):
  2823.  
  2824.                  set SWITCHCHARS=-
  2825.  
  2826.                You can  type options  in any  order (except where one
  2827.             overrides another,  in which  case the  last  setting  is
  2828.             used) and you group them together or type them separately
  2829.             as you  choose.   For example, ``ls -L -d -w'' is exactly
  2830.             the same  as ``ls -dwL''  and produces a very long format
  2831.             (very detailed)  list of the current directory, sorted by
  2832.             date (newest  ones last),  with sizes  of any directories
  2833.             filled in  by walking  down through  the directory  tree,
  2834.             adding up all the sizes of all the files found there.
  2835.  
  2836.  
  2837.  
  2838.                                      Page 39
  2839.  
  2840.      Utilities
  2841.  
  2842.  
  2843.                You can  always unambiguously  end  the  options  with
  2844.             ``--'' in  case you have a filename or an argument string
  2845.             that begins  with one  of option-introducing  characters.
  2846.             Also, since the shell does the wildcard expansion, it's a
  2847.             bit more  convenient and faster for the utilities to look
  2848.             for any options right at the beginning of what could be a
  2849.             very long list (up to 64 kilobytes) of filenames or other
  2850.             command-line text.
  2851.  
  2852.                We'll always  follow the  OS/2 and  NT  convention  of
  2853.             using ``\''  in filenames  in this  book and we generally
  2854.             advise that  you do  too, not so much because the C shell
  2855.             cares but  because so  much other  OS/2 and  NT  software
  2856.             does.   To some  fair degree,  it's a  case of  ``when in
  2857.             Rome, doing  as the  Romans do.''   But  if you really do
  2858.             prefer, you  can generally use ``/'' with the C shell and
  2859.             all the  utilities.   Do remember,  however, that  if you
  2860.             type a filename starting with ``/'' to mean the root, you
  2861.             have to be careful that it can't be confused as the start
  2862.             of an  option.  (This is a good use for the ``--'' option
  2863.             or the SWITCHCHARS variable.)
  2864.  
  2865.  
  2866.  
  2867.  
  2868.  
  2869.  
  2870.  
  2871.  
  2872.  
  2873.  
  2874.  
  2875.  
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.                                      Page 40
  2901.  
  2902.                                                                     Utilities
  2903.  
  2904.  
  2905.             echo
  2906.  
  2907.                echo is a little different than the vanilla OS/2 or NT
  2908.             echo.   It  does  only  one  thing:  it  prints  whatever
  2909.             arguments words  you give  it; there's no echo on or echo
  2910.             off-style status  reporting function.   But it does offer
  2911.             much finer control over what gets printed:  you can write
  2912.             binary values,  choose not to append a new line and write
  2913.             to stderr instead stdout.
  2914.  
  2915.                Here's an  example where  the  ANSI  escape  sequences
  2916.             turning brightness  on and off are embedded into a string
  2917.             being echoed.   The  ANSI escape  character is octal 033;
  2918.             binary  values  or  special  characters  like  ``[''  are
  2919.             introduced by the ``^'' shell escape.
  2920.  
  2921.                  11 D% echo Have a ^033^[1mnice^033^[0m day.
  2922.                  Have a nice day.
  2923.  
  2924.                (Processing of  the ^  escape sequences is done by the
  2925.             shell before  any command ever sees it.  As a result, you
  2926.             can  use  escape  sequences  to  construct  command  line
  2927.             arguments for  any command;  this feature  is  introduced
  2928.             here only  because it  tends to  be most  often used with
  2929.             echo.)
  2930.  
  2931.  
  2932.  
  2933.             mv, cp and rm:  Move, copy and remove
  2934.  
  2935.                The mv  (move), cp  (copy) and rm (remove) trio allows
  2936.             files and directories to be treated as simple objects.
  2937.  
  2938.                mv will move either files or directories treating them
  2939.             simply as  objects, even  across disk  partitions.     In
  2940.             this example,  the two  hello files  are moved into a new
  2941.             directory,  illustrating   how  mv  understands  that  if
  2942.             there's a  many-to-one relationship,  the destination has
  2943.             to be a directory.
  2944.  
  2945.                  12 D% mv hello* hello
  2946.                  13 D% ls
  2947.                  hello        memos        sysstuff
  2948.                  14 D% ls hello
  2949.                  hello.c      hello.exe
  2950.  
  2951.                Similarly, cp   will  copy a  file or  even an  entire
  2952.             directory.   The copies  cp  produces  are  always  exact
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.                                      Page 41
  2963.  
  2964.      Utilities
  2965.  
  2966.  
  2967.             logical copies,  with correct  timestamps+  and attribute
  2968.             bits and including any hidden or system files.
  2969.  
  2970.                  15 D% cp hello newhello
  2971.                  16 D% ls
  2972.                  hello        memos        newhello     sysstuff
  2973.                  17 D% ls -l hello
  2974.                  ---A-  Feb 23  12:56         72  hello.c
  2975.                  ---A-  Feb 23  12:57       7731  hello.exe
  2976.                  18 D% ls -l newhello
  2977.                  ---A-  Feb 23  12:56         72  hello.c
  2978.                  ---A-  Feb 23  12:57       7731  hello.exe
  2979.  
  2980.             cp does not consider it an error to copy over an existing
  2981.             file unless  the file  about to  be overwritten  has  its
  2982.             read-only bit set.
  2983.  
  2984.                Finally, rm   can  be used to remove a file or even an
  2985.             entire directory.   But  it does  insist that you tell it
  2986.             you really  mean it  if you  ask to  remove  a  directory
  2987.             that's not  empty or  anything  that's  marked  with  the
  2988.             system bit.
  2989.  
  2990.                  19 D% rm sysstuff
  2991.                  rm:  Can't remove system file 'systuff' without -S
  2992.                  option.
  2993.                  20 D% rm -S sysstuff
  2994.                  21 D% ls
  2995.                  hello        memos        newhello
  2996.                  22 D% rm newhello
  2997.                  rm:  Can't remove non-empty directory 'newhello'
  2998.                  without -r option.
  2999.                  23 D% rm -r newhello
  3000.                  24 D% ls
  3001.                  hello        memos
  3002.  
  3003.                As you  can see from these examples, the general style
  3004.             of the  utilities is  fairly terse.   Like the proverbial
  3005.             Vermonter, they  don't say  anything unless  they've  got
  3006.             something to  say.   Even copying or removing a directory
  3007.             happens without fanfare as long as the appropriate ``yes,
  3008.             I really mean it'' options are supplied.
  3009.  
  3010.  
  3011.  
  3012.             more
  3013.  
  3014.                more is an especially fast browsing filter.  There are
  3015.             two ways  to use  more.   The first is in a pipeline, the
  3016.  
  3017.             ____________________
  3018.             + Files only  under OS/2 1.1.  New directories always get
  3019.               the current timestamp unless you're running OS/2 1.2 or
  3020.               later.
  3021.  
  3022.  
  3023.  
  3024.                                      Page 42
  3025.  
  3026.                                                                     Utilities
  3027.  
  3028.  
  3029.             way ``vanilla''  more might  be used when you suspect the
  3030.             data may be longer than a screenful:
  3031.  
  3032.                  25 D% ls -l c:\os2\bin | more
  3033.                  :
  3034.                  :
  3035.  
  3036.             If the output turns out to be less than a screenful, it's
  3037.             as though  you'd just typed the ls command by itself.  In
  3038.             fact, there's  not even a noticeable performance penalty.
  3039.             But if  it's more  than a  screenful, more switches to an
  3040.             interactive mode  where you can use the arrow keys, etc.,
  3041.             to browse up and down through the listing.
  3042.  
  3043.                more can also be used for browsing a list of the files
  3044.             you give it on the command line:
  3045.  
  3046.                  26 D% more *.c
  3047.  
  3048.                more incorporates  the Berkeley  notion  referred  to,
  3049.             tongue-in-cheek, as  ``more is  less+'':    it's  a  good
  3050.             paging filter  that lets  you go  forwards and backwards.
  3051.             It also  offers a  number of different ways of looking at
  3052.             or  searching  the  data  including  binary,  as  control
  3053.             characters, line-numbered,  etc.  Perhaps most important,
  3054.             it's fast.
  3055.  
  3056.                Part of  more's speed  comes from an internal cache of
  3057.             about 11K  characters of  text  coupled  to  an  indexing
  3058.             structure that  it builds  on the  fly as  it  reads  the
  3059.             input.   When you  move forward  or backward  within  the
  3060.             cache, screen  redraw rates  are the  limiting factor  in
  3061.             performance.  Outside of range of the cache, if the input
  3062.             is from  a disk file, the indexing structure, technically
  3063.             an ISAM, tells more how to seek to the new location.
  3064.  
  3065.                There is  also a  ``huge''  version  of  more,  called
  3066.             moreh,  that  was  compiled  in  large  model  and  while
  3067.             slightly slower, has the advantage of caching up to about
  3068.             4M characters.   moreh  can be  useful when speed is less
  3069.             important than  being able  to scroll  all the  way  back
  3070.             through a large amount of text coming through a pipe.
  3071.  
  3072.  
  3073.  
  3074.             touch
  3075.  
  3076.             ____________________
  3077.             + The story  is now  a part of computer folk history:  at
  3078.               first, more  only went forward.  Then someone created a
  3079.               filter that  went backwards, which he aptly named less.
  3080.               When later  versions of  Berkeley's  more  incorporated
  3081.               this feature, they were heralded by announcements that,
  3082.               finally, ``more was less.''
  3083.  
  3084.  
  3085.  
  3086.                                      Page 43
  3087.  
  3088.      Utilities
  3089.  
  3090.  
  3091.                touch lets  you change  the timestamps  of  individual
  3092.             files  or  directories+  or,  using  the  -r  (recursive)
  3093.             option, of everything in a whole directory tree.
  3094.  
  3095.                If the  desired timestamp  isn't given, touch uses the
  3096.             current time.    If  the  filename  doesn't  exist,  it's
  3097.             created as a zero-length file.
  3098.  
  3099.                  27 D% ls
  3100.                  hello        memos
  3101.                  28 D% touch zork
  3102.                  29 D% ls
  3103.                  hello        memos        zork
  3104.  
  3105.  
  3106.  
  3107.             chmod
  3108.  
  3109.                chmod lets  you set a file's attributes but leaves the
  3110.             timestamp alone.   Here  is an example, first setting the
  3111.             system bit  (making it  show up in green), then making it
  3112.             hidden:
  3113.  
  3114.                  30 D% chmod +S zork
  3115.                  31 D% ls
  3116.                  hello        memos        zork
  3117.                  32 D% chmod +H zork
  3118.                  33 D% ls
  3119.                  hello        memos
  3120.  
  3121.             Of course,  the file  is still there and you can continue
  3122.             to manipulate its attributes:
  3123.  
  3124.                  34 D% ls -l zork
  3125.                  -SHA-  Feb 23  13:16         0  zork
  3126.                  35 D% ls +a
  3127.                  .              hello          zork
  3128.                  ..             memos
  3129.                  36 D% chmod +R zork
  3130.                  37 D% ls -l zork
  3131.                  -SHAR  Feb 23  13:16         0  zork
  3132.  
  3133.                Many users  will find that a file's system bit is more
  3134.             useful than they'd thought before.  With chmod, it's easy
  3135.             to set  or clear  the bit and setting it doesn't make the
  3136.             file hidden.   Quite the contrary, ls makes it stands out
  3137.             in green.   Also,  a file  marked ``system''  is a little
  3138.             safer from accidental deletion or overwriting.  These are
  3139.             often convenient characteristics to attach a few specific
  3140.             ____________________
  3141.             + On an  OS/2 1.1 system, the kernel allows you to change
  3142.               the  timestamps   only  on   files,  not   directories.
  3143.               touch'ing a directory does nothing unless you use the -
  3144.               r option to recursively touch the directory's contents.
  3145.  
  3146.  
  3147.  
  3148.                                      Page 44
  3149.  
  3150.                                                                     Utilities
  3151.  
  3152.  
  3153.             files within  a large directory.  For example, the author
  3154.             tends to routinely mark make files within a C source code
  3155.             directory as ``system'' just so they'll stand out.
  3156.  
  3157.  
  3158.  
  3159.             du, vol and pwd
  3160.  
  3161.                du, vol  and pwd  provide quick snapshots of your disk
  3162.             partitions:   du tells how much of the partition is used;
  3163.             vol  displays  the  label;  and  pwd  shows  the  current
  3164.             directory on each partition.
  3165.  
  3166.                  38 D% du
  3167.                  c: 31.904 M Total = 29.465 M Used + 2.439 M ( 7.65%)
  3168.                  Free  root
  3169.                  d: 23.920 M Total = 22.438 M Used + 1.482 M ( 6.20%)
  3170.                  Free  user
  3171.                  e: 13.957 M Total =  8.520 M Used + 5.438 M (38.96%)
  3172.                  Free  misc
  3173.                  39 D% pwd
  3174.                  c:\os2\include
  3175.                  d:\doug\sh\docs
  3176.                  e:\tmp
  3177.                  40 D% vol
  3178.                  c:  Jan 24  22:32:10  1988   root
  3179.                  d:  Nov 27  20:34:58  1988   user
  3180.                  e:  Jan 17  17:12:20  1988   misc
  3181.  
  3182.                A common  convention observed by the utilities is that
  3183.             if one  entry on  a list  is more current or special than
  3184.             the others,  it's highlighted.   du,  vol  and  pwd  each
  3185.             highlight the entry describing the current disk.
  3186.  
  3187.                For the  benefit of those who have lots of partitions,
  3188.             some of  which they  don't want to bother listing all the
  3189.             time, du,  vol and pwd look for a DRIVEMASK environmental
  3190.             variable which can be used to mask off just the drive you
  3191.             want.   This is  especially useful  for excluding  drives
  3192.             that take  removable media;  if they're  empty, they  can
  3193.             waste a  lot of time trying to read a diskette that's not
  3194.             there.
  3195.  
  3196.  
  3197.  
  3198.             dirs, pushd, popd and rotd
  3199.  
  3200.                The shell  provides a  built-in mechanism  for keeping
  3201.             several directories  ``handy.''   This mechanism  is  the
  3202.             directory stack,  which always  contains a list of fully-
  3203.             qualified directory  pathnames with the current directory
  3204.             at the  top.   You can  display the  list with  the  dirs
  3205.             command:
  3206.  
  3207.  
  3208.  
  3209.  
  3210.                                      Page 45
  3211.  
  3212.      Utilities
  3213.  
  3214.  
  3215.                  41 D% dirs
  3216.                  d:\doug\sh\docs
  3217.  
  3218.                Initially  the   list  contains   only  your   current
  3219.             directory.   When you  push a  new directory on the stack
  3220.             with pushd,  that  becomes  your  new  current  disk  and
  3221.             current directory.   pushd  also  reports  the  resulting
  3222.             stack contents.
  3223.  
  3224.                  42 D% pushd c:
  3225.                  c:\os2\include
  3226.                  d:\doug\sh\docs
  3227.                  43 C% pushd e:
  3228.                  e:\tmp
  3229.                  c:\os2\include
  3230.                  d:\doug\sh\docs
  3231.  
  3232.                Calling pushd without any arguments just swaps the top
  3233.             two directories:
  3234.  
  3235.                  44 E% pushd
  3236.                  c:\os2\include
  3237.                  e:\tmp
  3238.                  d:\doug\sh\docs
  3239.  
  3240.                Popping elements  off the  stack is  done  with  popd,
  3241.             which also reports the resulting stack.
  3242.  
  3243.                  45 C% popd
  3244.                  e:\tmp
  3245.                  d:\doug\sh\docs
  3246.  
  3247.                The stack  can also be rotated with rotd.  (We'll push
  3248.             another directory  first so  we can  see that rotation is
  3249.             upward, with  the top  item going  to the  bottom of  the
  3250.             stack.)
  3251.  
  3252.                  46 E% pushd \
  3253.                  e:\
  3254.                  e:\tmp
  3255.                  d:\doug\sh\docs
  3256.                  47 E% rotd
  3257.                  e:\tmp
  3258.                  d:\doug\sh\docs
  3259.                  e:\
  3260.  
  3261.                You can pop multiple directory entries at once, but if
  3262.             you ask to pop more than exist, you'll get a message:
  3263.  
  3264.                  48 E% popd 5
  3265.                  csh:  The built-in popd command can only accept a
  3266.                  integer argument n, where n > 0 && n < number of
  3267.                  elements on the directory stack.  The default for n
  3268.                  is 1.
  3269.  
  3270.  
  3271.  
  3272.                                      Page 46
  3273.  
  3274.                                                                     Utilities
  3275.  
  3276.  
  3277.                  49 E% popd
  3278.                  d:\doug\sh\docs
  3279.                  e:\
  3280.  
  3281.  
  3282.  
  3283.             fgrep and grep
  3284.  
  3285.                fgrep and  grep  are  fast  string  search  utilities.
  3286.             Their  names   and  the  regular  expression  syntax  are
  3287.             traditional; it's an accepted standard and we've followed
  3288.             it.
  3289.  
  3290.                 fgrep and grep are used to scan through long lists of
  3291.             files or filter data coming through a pipe for strings or
  3292.             patterns you  specify.   They'll quickly  report all  the
  3293.             matching lines.   If  you like,  you can get more or less
  3294.             detail in  the output,  e.g., have  line numbers shown or
  3295.             just get a total count of all the matches.
  3296.  
  3297.                fgrep and  grep both  have the  ability to  look for a
  3298.             large number  of patterns in parallel (using the -s or -f
  3299.             options)   with   almost   no   discernable   performance
  3300.             degredation.   They're very  fast.   Both precompile  and
  3301.             optimize their  search patterns,  use direct  kernel  api
  3302.             calls for  all  i/o  and  use  a  very  high  performance
  3303.             buffering structure  to allow  extremely fast scanning of
  3304.             large amounts of data.
  3305.  
  3306.  
  3307.  
  3308.             fgrep
  3309.  
  3310.                fgrep is  the simpler  and slightly  faster of the two
  3311.             search utilities.    It  does  a  simple  string  compare
  3312.             between the  string you're looking for and the characters
  3313.             on each  line.  If the search string is found anywhere on
  3314.             the line,  it's a  match.   There are  some  options  for
  3315.             ignoring  differences  in  upper-/lower-case  or  in  the
  3316.             amount of white space (spaces and tabs) between words but
  3317.             but mostly it's quite simple comparison.
  3318.  
  3319.                Here's an  example of  using fgrep  to search  a  very
  3320.             simple personal phone directory where each record is just
  3321.             a line  of text and we'll search it .  (Later we'll learn
  3322.             how to  package things like this up into aliases or shell
  3323.             procedures  so   you  can  call  them  with  just  a  few
  3324.             keystrokes.)
  3325.  
  3326.                  50 D% fgrep -i doctor \phone
  3327.                  Doctor James Gardner    508-999-0000  12 Canton St
  3328.                  Doctor Karen Strickland 508-721-1223  N.E. Medical
  3329.                  Offices
  3330.  
  3331.  
  3332.  
  3333.  
  3334.                                      Page 47
  3335.  
  3336.      Utilities
  3337.  
  3338.  
  3339.             grep
  3340.  
  3341.                grep  looks   for  special   patterns  called  regular
  3342.             expressions, which are similar to (but slightly different
  3343.             from) filename  wildcarding.   The grammar  is recursive,
  3344.             meaning  a  regular  expression  to  be  matched  can  be
  3345.             written,  in   turn,  as   a  nested  series  of  regular
  3346.             expressions:
  3347.  
  3348.                c      Any ordinary character matches itself.
  3349.                \c     Match the literal character c.
  3350.                ^      Beginning of line.
  3351.                $      End of line.
  3352.                .      Match any single character.
  3353.                [...]  Match any single character in the list.
  3354.                [^...] Match any single character not in the list.
  3355.                \n     Match whatever  literal text  the  n'th  tagged
  3356.                       \(...\) expression matched.
  3357.                r*     Match zero or more occurrences of r.
  3358.                r1r2   Match expression r1 followed by r2.
  3359.                \(r\)  Tagged regular  expression.   Match the pattern
  3360.                       inside the  \(...\), and  remember the  literal
  3361.                       text that matched.
  3362.                At the  lowest layer,  you give  a character or set of
  3363.             characters to  be matched anchored, if you want, to match
  3364.             just the  beginning or  just the  end of  a line.  At the
  3365.             next layer, the ``*'' character lets you match a variable
  3366.             number of repetitions of a pattern.
  3367.  
  3368.                When you  type a  regular expression  on  the  command
  3369.             line, keep  in mind:   (1)  Many of  the characters  have
  3370.             special meaning  to the  C shell  and have  to be  inside
  3371.             quotes.  (2) You have to type two ``^'s'' to get just one
  3372.             because ``^''  is the  shell's literal  escape character.
  3373.             (3) ``*''  is a  postfix operator.   It  operates on  the
  3374.             preceding regular  expression; by  itself, it  is  not  a
  3375.             ``match zero  or more  characters'' wildcard character as
  3376.             you may be used to with filenames.
  3377.  
  3378.                Here's an  example of searching through all the source
  3379.             code for a large application, looking for all occurrences
  3380.             of lines  that begin  with ``statement''  followed  by  a
  3381.             ``y'' somewhere  on the line and showing the line numbers
  3382.             of any  matches.   (The -s option tells pushd and popd to
  3383.             work silently.)
  3384.  
  3385.                  51 D% pushd -s ~\sh
  3386.                  52 D% grep -n '^^statement.*y' *.c
  3387.                  allocate.c:418:statement_obj
  3388.                  *allocate_statement(size, type)
  3389.                  53 D% popd -s
  3390.  
  3391.  
  3392.  
  3393.  
  3394.  
  3395.  
  3396.                                      Page 48
  3397.  
  3398.                                                                     Utilities
  3399.  
  3400.  
  3401.             sed
  3402.  
  3403.                sed is  a stream  editor.   Just as you might think of
  3404.             using a  regular editor  to  edit  a  file,  deleting  or
  3405.             inserting lines,  doing search/replace  operations, etc.,
  3406.             sed lets you edit a stream of data:  individual lines are
  3407.             read from  stdin, edited according to the script you give
  3408.             and written  to stdout.   A  very simple  sort of  script
  3409.             might be  given right  on the  command line.    Here's  a
  3410.             simple search/replace:
  3411.  
  3412.                  54 D% echo hello world | sed s/world/everybody/
  3413.                  hello everybody
  3414.  
  3415.                sed uses  the same  regular expressions  used by grep.
  3416.             It's possible  to pick  up pieces  of the input as tagged
  3417.             expressions and  move them  around.  In this example, the
  3418.             two strings  on either side of the space are tagged, then
  3419.             swapped   around.      Quotes   are   used   around   the
  3420.             search/replace command  so the  C shell  will treat it as
  3421.             one  long   literal  string   to  be   passed   to   sed.
  3422.             (Parentheses, spaces and asterisks otherwise have special
  3423.             meaning.)   Notice how the ``*'' construct, meaning match
  3424.             zero  or   more  occurrences  actually  matches  as  many
  3425.             repetitions as possible.
  3426.  
  3427.                  55 D% echo hello world | sed 's/\(.*\) \(.*\)/\2
  3428.                  \1/'
  3429.                  world hello
  3430.  
  3431.                For more  complex operations,  sed offers a wide array
  3432.             of operators  including even  conditional branches  and a
  3433.             hold buffer  where a string can be saved temporarily from
  3434.             one line  to the  next.  If your script is very long, the
  3435.             -f option lets you specify it in a file.
  3436.  
  3437.  
  3438.  
  3439.             diff
  3440.  
  3441.                diff is  an extremely  fast and  flexible utility  for
  3442.             quickly comparing  ascii files,  looking for differences.
  3443.             In the  simplest form,  you simply  give it two filenames
  3444.             corresponding to  the old  and new versions and let it go
  3445.             to work,  reporting sections  that have  been deleted  or
  3446.             added in  a  traditional  format.    For  example,  as  a
  3447.             software developer, I might use it to compare old and new
  3448.             versions of a C program:
  3449.  
  3450.                  56 D% diff archive\parse.c parse.c
  3451.                  1493 c 1493
  3452.                  <          d->inline_cnt = src->inline_cnt++;
  3453.                  ---
  3454.                  >          d->inline_cnt = ++src->inline_cnt;
  3455.  
  3456.  
  3457.  
  3458.                                      Page 49
  3459.  
  3460.      Utilities
  3461.  
  3462.  
  3463.             Each change  is reported  in terms  of the line number or
  3464.             range in  the old  version,  whether  it's  an  addition,
  3465.             change or  deletion, the  line numbers in the new version
  3466.             and then  the affected lines from each file, separated by
  3467.             a line of ``---''.
  3468.  
  3469.                diff supports  the traditional  options  for  ignoring
  3470.             differences in  upper-/lower-case or  in  the  amount  of
  3471.             white space on the line, for recursively comparing entire
  3472.             directory trees of files, etc.
  3473.  
  3474.                One of  diff's most novel features is its ability with
  3475.             the -!  option to  generate a  merged listing  where text
  3476.             that's deleted  is shown  in red,  new text  is shown  in
  3477.             green and  the rest is displayed normally.  This makes it
  3478.             extremely easy  to view your changes in context.  (To use
  3479.             this option,  remember that  ``!'' is a special character
  3480.             to the  shell; type  it at  the end of the option list so
  3481.             there'll be a space following.)
  3482.  
  3483.  
  3484.  
  3485.             head and tail
  3486.  
  3487.                head and  tail are  used to  display just the first or
  3488.             last few  lines or  characters of a file.  Normally, they
  3489.             expand any  tabs into  spaces so you don't need to filter
  3490.             them through more.
  3491.  
  3492.                tail is  particularly interesting.  If all you want is
  3493.             the end  of a  very large  file, tail  doesn't waste time
  3494.             reading the whole file from start to finish.  Instead, it
  3495.             jumps right  to the  end and  reads it backwards!  If the
  3496.             file is  truly large  (on the order of several megabytes)
  3497.             and all you want is a little bit off the end, this is the
  3498.             difference between  chugging along  for  several  seconds
  3499.             versus getting an almost instantaneous response.
  3500.  
  3501.                tail also  has a -f follow option.  What that means is
  3502.             that when  it gets  to the  end of  file,  it  enters  an
  3503.             endless loop,  sleeping for  a second,  then waking up to
  3504.             see if  more has been added.  This is particularly useful
  3505.             if, e.g., you have an operation, say a large make, active
  3506.             in one window with its output redirected to a file.  From
  3507.             another window  you can  periodically  check  in  on  the
  3508.             progress by typing:
  3509.  
  3510.                  57 D% tail -f e:\tmp\make.log
  3511.                  :
  3512.                  ^C
  3513.  
  3514.             tail lets  you watch  lines get  added without  consuming
  3515.             much processor  resource (since  it sleeps  in the kernel
  3516.             most of  the time) so you can watch a background activity
  3517.  
  3518.  
  3519.  
  3520.                                      Page 50
  3521.  
  3522.                                                                     Utilities
  3523.  
  3524.  
  3525.             progress without affecting its performance.  After you've
  3526.             watched for  a while,  just type  ^C to interrupt and get
  3527.             out.   The interrupt  only goes  to the tail program; the
  3528.             application off  in the  background or  in another window
  3529.             creating the  file is  not affected  and will go on about
  3530.             its business  until you  come back once again to check on
  3531.             it.
  3532.  
  3533.  
  3534.  
  3535.             cut
  3536.  
  3537.                cut is  a simple filter for selecting out just certain
  3538.             fields or character positions of each line of input.  You
  3539.             choose what characters should be interpreted as the field
  3540.             delimiters and  which fields  should  be  copied  to  the
  3541.             output.   For example,  if you  kept your  phone book  in
  3542.             \phone, you might strip off just the first word from each
  3543.             line to get everyone's first names:
  3544.  
  3545.                  58 D% cut -f1 -d' ' \phone
  3546.                  Ed
  3547.                  Helen
  3548.                  Jack
  3549.                  Vickie
  3550.                  :
  3551.  
  3552.             The  -f  option  means  you  want  to  count  by  fields,
  3553.             selecting the  first field  and that  the delimiter  is a
  3554.             space character.  (Notice the quotes around the space.)
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.                                      Page 51
  3583.  
  3584.      Utilities
  3585.  
  3586.  
  3587.             split
  3588.  
  3589.                split lets  you break  up a  large file  into smaller,
  3590.             fixed-size  pieces   counting  either   by  lines  or  by
  3591.             characters.   Each of  the smaller  files it  creates are
  3592.             numbered, e.g., chunk.001, chunk.002, chunk.003, etc.
  3593.  
  3594.                One example  of where  you might use split might be if
  3595.             you had  a very  large file you wanted to transmit over a
  3596.             modem.   If the  line dropped suddenly, you wouldn't want
  3597.             to have  to start all over on a 2M file.  If you split it
  3598.             first into  200K chunks,  you'd stand to lose a lot less.
  3599.             Another example might be if you had a truly enormous text
  3600.             file that  was just  too big  to easily  edit  with  your
  3601.             favorite editor.  Splitting it up into chunks of only 10K
  3602.             lines each might be a solution.
  3603.  
  3604.  
  3605.  
  3606.             tabs
  3607.  
  3608.                tabs lets  you expand or unexpand tab characters based
  3609.             on a  set of  tab settings you give it.  Tab settings are
  3610.             religious.   I like  them every 3 spaces but you probably
  3611.             like something else.  If you're composing something to be
  3612.             sent as  email  or  posted  on  a  bulletin  board,  it's
  3613.             probably nice  to expand  it out  before you  send it  so
  3614.             everyone sees what you see.
  3615.  
  3616.  
  3617.  
  3618.             tr
  3619.  
  3620.                tr  is   a  another   simple  filter  for  translating
  3621.             characters from  input to output.  For example, you could
  3622.             translate everything from lower to upper case by typing:
  3623.  
  3624.                  59 D% tr a-z A-Z
  3625.                  hello world
  3626.                  HELLO WORLD
  3627.                  ^Z
  3628.  
  3629.             We typed  the first hello world and tr has just echoed it
  3630.             in upper  case.   ^Z is the end-of-file character defined
  3631.             by OS/2 and NT.
  3632.  
  3633.                tr also  has a  number of  options for  squeezing  out
  3634.             repeated sequences  of the  same character or editing out
  3635.             just certain characters and even for normalizing the text
  3636.             in a  file, ensuring that every line ends with a carriage
  3637.             return/line feed  combination.   That's handy  if  you're
  3638.             importing a file from another operating system.
  3639.  
  3640.  
  3641.  
  3642.  
  3643.  
  3644.                                      Page 52
  3645.  
  3646.                                                                     Utilities
  3647.  
  3648.  
  3649.              strings
  3650.  
  3651.                strings lets you simply list out all the ASCII strings
  3652.             in an  otherwise binary  file.   Sometimes  this  can  be
  3653.             useful for  spelunking around  through a file when you're
  3654.             really not  sure at  all just  what's inside it.  Various
  3655.             options are  available to  trimming the  output  so  only
  3656.             strings of  a minimum  length, etc.,  will be shown.  For
  3657.             example,
  3658.  
  3659.                  60 D% strings hello.exe
  3660.                  !This program cannot be run in DOS mode.
  3661.                  :
  3662.                  Hello, world
  3663.                  :
  3664.  
  3665.                Another  example   might  be   if  you   suspected  an
  3666.             application was  carrying a  virus.   Naturally,  strings
  3667.             can't guarantee something's free of any virus, but on the
  3668.             other  hand,  if  you  scan  it  with  strings  and  find
  3669.             something like this, obviously you should be careful:
  3670.  
  3671.                  61 D% strings a:suspect.exe
  3672.                  :
  3673.                  Aha!  Gotcha!  I just blew away your hard disk!
  3674.  
  3675.  
  3676.  
  3677.             dskread and dskwrite
  3678.  
  3679.                This pair  of utilities  can be  used to quickly copy,
  3680.             format or  mass duplicate  diskettes in  a  single  pass.
  3681.             Here's an  example using dskread to read a whole diskette
  3682.             image onto your hard disk and then write it back out onto
  3683.             a new floppy with dskwrite.  The dskwrite -a option means
  3684.             autoformat,  i.e.,   if  the   new  disk   isn't  already
  3685.             formatted, format  each track  as it's  written.   The -v
  3686.             option means read back and verify each write to be sure a
  3687.             good copy was made.
  3688.  
  3689.                  62 D% dskread a: >disk.image  # Read the whole
  3690.                  diskette
  3691.                  63 D% dskwrite -av a: <disk.image  # Make a new copy
  3692.  
  3693.                To make  more copies,  you  simply  keep  putting  new
  3694.             diskettes in  and rerunning  the  dskwrite.    Since  the
  3695.             entire diskette  image,  including  the  boot  sector  is
  3696.             captured onto  the hard disk by dskread, it's possible to
  3697.             email a  bootable diskette  image,  even  compressing  it
  3698.             first with  one of the popular compression utilities such
  3699.             as arc or pkzip.
  3700.  
  3701.                dskread and  dskwrite can  also be used to copy a very
  3702.             large file  onto a  whole series of diskettes and restore
  3703.  
  3704.  
  3705.  
  3706.                                      Page 53
  3707.  
  3708.      Utilities
  3709.  
  3710.  
  3711.             it later  as a  single file.   E.g., to back up your hard
  3712.             disk, you  might compress  whole directories using one of
  3713.             the popular compression utilities and write the resulting
  3714.             archive file  out as  1.2MB (or,  as appropriate,  1.4MB)
  3715.             chunks onto  separate diskettes.   To  restore the  file,
  3716.             just cat  or dskread  the pieces together again.  (But if
  3717.             you do  try this, be sure the compression utility you use
  3718.             can handle  any long  filenames or system or hidden files
  3719.             you have lurking in your directories.)
  3720.  
  3721.                Here's an example of writing a very large .zip file to
  3722.             a series  of diskettes.   The  -c option  means it should
  3723.             continue with  as many  diskettes as it takes to hold all
  3724.             the data,  prompting you  for each  new diskette  when it
  3725.             needs it.  The -d option causes it to write  a dummy file
  3726.             system around  the data (so it still looks like a regular
  3727.             OS/2 or  NT diskette).   The  -n option takes an argument
  3728.             specifying the  name given  the file being created on the
  3729.             diskette.   In this example, the first diskette will have
  3730.             a  file   named  ``big.001'',   the  second   will   have
  3731.             ``big.002'', etc.   Once  again,  the  -av  options  mean
  3732.             autoformat and verify each write.
  3733.  
  3734.                  64 D% dskwrite -avcd -n big a: < g:big.zip
  3735.  
  3736.                To get  it all  back, you  could simply  copy all  the
  3737.             pieces individually onto your hard disk and then cat them
  3738.             together or use dskread to do it for you:
  3739.  
  3740.                  65 D% dskread -dc -n big a: > g:big.zip
  3741.  
  3742.  
  3743.  
  3744.             Other Utilities
  3745.  
  3746.                Other utilities provide means for sleeping for a timed
  3747.             period, counting the number of words in a file and so on.
  3748.             Part of  the appeal  of Hamilton  C shell  is  that  it's
  3749.             relatively easy  to continue  expanding  the  vocabularly
  3750.             with simple utilities that may each be only a few hundred
  3751.             lines long.
  3752.  
  3753.                This has  been a  fast introduction.  Fortunately, you
  3754.             don't have  to learn  the utilities  just from  the book.
  3755.             All have  on-line information  available  with  -h.    We
  3756.             encourage you to experiment.
  3757.  
  3758.                As this  is being  written, we're still giving thought
  3759.             to additional  utilities.   If you  have favorites  you'd
  3760.             like to  see included  or maybe  offered as new products,
  3761.             please contact us.
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.                                      Page 54
  3769.  
  3770.                                                               I/O Redirection
  3771.  
  3772.  
  3773.             
  3774.  
  3775.  
  3776.                            I/O Redirection and Piping
  3777.  
  3778.  
  3779.  
  3780.  
  3781.             I/O Redirection
  3782.  
  3783.                You can redirect or pipe i/o in much the way you might
  3784.             under cmd.exe.    Here's  a  simple  example  redirecting
  3785.             stdout from the word count of the famous ``Hello, world''
  3786.             program.   cat just copies from any files you tell it or,
  3787.             by default, from stdin to stdout.
  3788.  
  3789.                  66 E% cd hello
  3790.                  67 D% ls
  3791.                  hello.c      hello.exe
  3792.                  68 D% cat hello.c
  3793.                  #include <stdio.h>
  3794.                  main ()
  3795.                     {
  3796.                     printf("Hello, world.\n");
  3797.                     }
  3798.                  69 D% wc hello.c >hello.wc
  3799.                  70 D% cat <hello.wc
  3800.                          5        8       72  hello.c
  3801.  
  3802.             (wc tells  us that  hello.c has  5  lines,  containing  8
  3803.             words, totalling 72 characters.)
  3804.  
  3805.                If the file you write to with ``>'' exists, it's first
  3806.             truncated to  zero length  (discarding the old contents);
  3807.             if the  file doesn't  exist, it's  created.   With ``<'',
  3808.             it's an error if the file doesn't exist.
  3809.  
  3810.                Data can  be  appended  to  a  file  with  the  ``>>''
  3811.             operator:
  3812.  
  3813.                  71 D% echo that^'s all folks >>hello.wc
  3814.                  72 D% cat hello.wc
  3815.                          5        8       72  hello.c
  3816.                  that's all folks
  3817.                  73 D% _
  3818.  
  3819.             When you  append with ``>>'', if the file exists, data is
  3820.             written onto  the end; if it doesn't exist, it's created.
  3821.             (The single  quote character  has special  meaning to the
  3822.             shell on  the command line; the special meaning is turned
  3823.             off by the shell's escape character,``^''.)
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.                                      Page 55
  3831.  
  3832.      I/O Redirection
  3833.  
  3834.  
  3835.             noclobber
  3836.  
  3837.                Not everyone  is comfortable  with letting  the  shell
  3838.             glibly toss  away an existing file if you type ``>'' when
  3839.             you meant  ``>>'' or  lose it somewhere if you mistype an
  3840.             existing filename  with ``>>''.   The  noclobber variable
  3841.             lets you  tell the  shell you  want this to be caught, so
  3842.             you can decide if this was really what you meant.
  3843.  
  3844.                If you  set noclobber,  you have  to  type  ``>!''  to
  3845.             redirect to an existing file:
  3846.  
  3847.                  73 D% set noclobber = 1
  3848.                  74 D% echo trash this file > hello.c
  3849.                  csh:  Couldn't open 'hello.c' as a redirected
  3850.                  standard output.
  3851.  
  3852.             Come to think of it, let's not overwrite that file.
  3853.  
  3854.                Similarly if  you want  to append  to  something  that
  3855.             doesn't already exist:
  3856.  
  3857.                  75 D% echo appended data >> newdata
  3858.                  csh:  Couldn't open 'newdata' as a redirected
  3859.                  standard output.
  3860.                  76 D% echo appended data >>! newdata
  3861.                  77 D% cat newdata
  3862.                  appended data
  3863.                  78 D% rm newdata
  3864.  
  3865.  
  3866.  
  3867.             Protection Attributes
  3868.  
  3869.                If  a   file  has   any  of   the  special  protection
  3870.             attributes, hidden,  read-only or system, set, you cannot
  3871.             overwrite it  by redirecting  i/o to  it.   Even when you
  3872.             type ``!'',  you still can't.  Before you can redirect to
  3873.             it, you must clear all these attribute bits.
  3874.  
  3875.                  79 D% ls -l zork
  3876.                  -SHAR  Feb 23  13:16         0  zork
  3877.                  80 D% echo new zork data >! zork
  3878.                  csh:  Couldn't open 'zork' as a redirected standard
  3879.                  output.
  3880.                  81 D% chmod -R zork
  3881.                  82 D% echo new zork data >! zork
  3882.                  csh:  Couldn't open 'zork' as a redirected standard
  3883.                  output.
  3884.                  83 D% chmod -SH zork
  3885.                  84 D% ls -l zork
  3886.                  ---A-  Feb 23  13:16         0  zork
  3887.                  85 D% echo new zork data > zork
  3888.                  86 D% _
  3889.  
  3890.  
  3891.  
  3892.                                      Page 56
  3893.  
  3894.                                                               I/O Redirection
  3895.  
  3896.  
  3897.             Stdout and Stderr
  3898.  
  3899.                Redirecting both stdout and stderr together is done by
  3900.             adding an  ampersand.   For example,  using echo's ``-2''
  3901.             option to  deliberately write  to stderr  and parentheses
  3902.             for a simple grouping:
  3903.  
  3904.                  86 D% (echo -2 error; echo standard) > zork
  3905.                  error
  3906.                  87 D% cat zork
  3907.                  standard
  3908.                  88 D% (echo -2 error; echo standard) >& zork
  3909.                  89 D% cat zork
  3910.                  error
  3911.                  standard
  3912.                  90 D% _
  3913.  
  3914.                Separately redirecting  stderr and stdout to different
  3915.             files is  a little tricky:  first you redirect them both,
  3916.             then redirect  stdout  by  itself.    Here's  an  example
  3917.             running the  C compiler  with stdout  to log  and  stderr
  3918.             going to errors.
  3919.  
  3920.                  90 D% cl hello.c >& errors > log
  3921.  
  3922.             You can  type as  many i/o  redirections in  a row as you
  3923.             like.   The shell  evaluates them  one after another.  If
  3924.             you redirect  to a  new file,  then redirect to something
  3925.             else, the effect is just like touch'ing the file.
  3926.  
  3927.  
  3928.  
  3929.             Pipes
  3930.  
  3931.                Pipes are  a way  of connecting a series of activities
  3932.             together so  that the  output of  one is read as input to
  3933.             the next.  Each of the activities runs asynchronously and
  3934.             concurrently with  the others.  Data is passed completely
  3935.             in memory and is very fast.
  3936.  
  3937.                The syntax is similar to i/o redirection in its use of
  3938.             the ``&''  character.  To pipe just stdout, use  ``|'' by
  3939.             itself:
  3940.  
  3941.                  91 D% ls -L | more
  3942.  
  3943.             To pipe both stdout and stderr together, use ``|&'':
  3944.  
  3945.                  92 D% cl hello\hello.c |& more
  3946.  
  3947.                The  leftmost   part  of  the  pipeline  is  evaluated
  3948.             directly by  the shell's  current thread.  The successive
  3949.             right parts  are evaluated by child threads.  (This is so
  3950.             that piping  a command  that lists  status information on
  3951.  
  3952.  
  3953.  
  3954.                                      Page 57
  3955.  
  3956.      I/O Redirection
  3957.  
  3958.  
  3959.             the current  thread through  a filter  like more operates
  3960.             sensibly.)     Each  part  of  the  pipeline  can  be  an
  3961.             arbitrarily complex  statement, perhaps  even  run  as  a
  3962.             separate OS/2 screen group or in a separate NT window.
  3963.  
  3964.                Pipes are  much faster  and more  responsive than with
  3965.             vanilla  OS/2   or  NT  due  to  improved  buffering  and
  3966.             scheduling technology.   A  long pipeline  finishes  much
  3967.             faster.   Also, when  you type  ^C to interrupt, it comes
  3968.             back immediately without a lot of nuisance messages.
  3969.  
  3970.  
  3971.  
  3972.  
  3973.  
  3974.  
  3975.  
  3976.  
  3977.  
  3978.  
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.                                      Page 58
  4017.  
  4018.                                                               I/O Redirection
  4019.  
  4020.  
  4021.             Command Substitution
  4022.  
  4023.                A particularly novel way of piping statements together
  4024.             is to  use the output of one as command line arguments of
  4025.             another.   This is  called command  substitution and  you
  4026.             indicate  it   by  typing  backquotes,  `...`,  around  a
  4027.             command.
  4028.  
  4029.                  93 D% ls +a
  4030.                  .              hello          zork
  4031.                  ..             memos
  4032.                  94 D% echo `ls +a`
  4033.                  . hello zork .. memos
  4034.                  95 D% _
  4035.  
  4036.                When command  substitution  is  done,  all  the  extra
  4037.             ``white space''  (space characters, tabs and newlines) is
  4038.             squeezed out.  Also, any ANSI escape sequences that might
  4039.             have turned  on highlighting or color, etc., are deleted.
  4040.             You just  get the  list of  words the  backquoted command
  4041.             wrote to stdout.  In this example, the order of the files
  4042.             is a bit scrambled when the line ends are removed; the -1
  4043.             (numeric one) single column option can fix this.  (Try it
  4044.             again using ls +a1 inside the backquotes.)
  4045.  
  4046.                Command substitution is especially useful anywhere you
  4047.             need to  give a  list of  filenames  as  arguments  to  a
  4048.             command.   Here's an  example using ls to give a detailed
  4049.             listing of the two more filters, the old and the new:
  4050.  
  4051.                  95 D% whereis more
  4052.                  c:\hamilton\more.exe
  4053.                  c:\os2\more.com
  4054.                  96 D% ls -l `whereis more`
  4055.                  ---A-  Mar 20  8:00      20123  c:\hamilton\more.exe
  4056.                  ---A-  Oct 26 12:00      31658  c:\os2\more.com
  4057.  
  4058.             (Our more is ``less filling and tastes better.'')
  4059.  
  4060.                The string inside the backquotes is passed directly to
  4061.             a child  thread for  interpretation.   If there  are  any
  4062.             variable substitutions  inside  the  backquotes,  they're
  4063.             done by  the child, not the parent.  This lets you easily
  4064.             embed for loops and other programming constructs into the
  4065.             command substitution.
  4066.  
  4067.                Inside backquotes,  only the backquote character needs
  4068.             to be  escaped to avoid having it processed by the parent
  4069.             thread.
  4070.  
  4071.  
  4072.  
  4073.             Inline Data
  4074.  
  4075.  
  4076.  
  4077.  
  4078.                                      Page 59
  4079.  
  4080.      I/O Redirection
  4081.  
  4082.  
  4083.                A novel  variation on  i/o redirection is inline data,
  4084.             also called  ``here'' documents:   literal  text you want
  4085.             the shell to feed a command as stdin.  Here's an example:
  4086.  
  4087.  
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.  
  4098.  
  4099.  
  4100.  
  4101.  
  4102.  
  4103.  
  4104.  
  4105.  
  4106.  
  4107.  
  4108.  
  4109.  
  4110.  
  4111.  
  4112.  
  4113.  
  4114.  
  4115.  
  4116.  
  4117.  
  4118.  
  4119.  
  4120.  
  4121.  
  4122.  
  4123.  
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.                                      Page 60
  4141.  
  4142.                                                               I/O Redirection
  4143.  
  4144.  
  4145.                  97 D% cat <<eof
  4146.                  98 D? (this is the inline data)
  4147.                  99 D? eof
  4148.                  (this is the inline data)
  4149.                  100 D% _
  4150.  
  4151.             The ``<<''  operator is followed by a string the shell is
  4152.             asked to  look for  to mark  the end  of the inline data.
  4153.             The end-of-data  string can  be  virtually  anything  you
  4154.             like, including  wildcard characters, dollar signs, etc.;
  4155.             their normal meaning is turned off and they're treated as
  4156.             ordinary  literal  characters.    Only  quote  or  escape
  4157.             characters have any special meaning, which is to turn off
  4158.             substitutions in  the inline  text (as we'll discuss in a
  4159.             moment).   Continuation lines  as the  shell collects the
  4160.             inline data  get a  different prompt,  controlled by  the
  4161.             prompt2 variable.   Once  the data  has been collected in
  4162.             memory, it's written through a pipe to the command.
  4163.  
  4164.                One very  convenient use  of inline  data is  when you
  4165.             want to  quickly search  for  any  one  of  a  number  of
  4166.             important words  in a  large library.   E.g., to scan for
  4167.             some specific strings in a set of C files:
  4168.  
  4169.                  100 D% fgrep -ns <<xxx ~\sh\*.c
  4170.                  101 D? DosOpen
  4171.                  102 D? DosClose
  4172.                  103 D? DosRead
  4173.                  104 D? DosWrite
  4174.                  105 D? xxx
  4175.                  :  search results
  4176.  
  4177.                In situations  where the  inline data is being created
  4178.             inside a  larger structure,  the data is assumed to start
  4179.             on the  first line  following a break between statements.
  4180.             For example, inside a for loop:
  4181.  
  4182.                  106 D% for i = 1 to 3 do
  4183.                  107 D? cat <<eof; echo i = $i
  4184.                  108 D? (this is the inline data)
  4185.                  109 D? eof
  4186.                  110 D? end
  4187.                  (this is the inline data)
  4188.                  i = 1
  4189.                  (this is the inline data)
  4190.                  i = 2
  4191.                  (this is the inline data)
  4192.                  i = 3
  4193.  
  4194.                If you  want to put several inline i/o redirections on
  4195.             the same  line, type the associated inline data sections,
  4196.             each with  its own  terminating string, in the same left-
  4197.             to-right order in which they appeared.
  4198.  
  4199.  
  4200.  
  4201.  
  4202.                                      Page 61
  4203.  
  4204.      I/O Redirection
  4205.  
  4206.  
  4207.                So far,  we've just  shown examples  involving  static
  4208.             text.   But it's  also possible  to ask  the shell  to do
  4209.             command and variable substitutions on the inline text:
  4210.  
  4211.                  111 D% cat << ***
  4212.                  112 D? The ^$home directory is $home.
  4213.                  113 D? Today's date is `date`.
  4214.                  114 D? ***
  4215.                  The $home directory is d:\doug
  4216.                  Today's date is Wed   Mar 17 1993   14:40:51.12.
  4217.                  115 D% _
  4218.  
  4219.                Notice  that   although   substitutions   and   escape
  4220.             characters inside the here document are processed, quotes
  4221.             (both single and double) are not.
  4222.  
  4223.                [The C  shell implements  here documents by spawning a
  4224.             child thread  to  do  any  substitutions  and  write  the
  4225.             results into  a pipe  feeding the  current thread  as  it
  4226.             continues  to  evaluate  the  statement.    If  the  here
  4227.             document contains references to shared variables, they'll
  4228.             be evaluated  by that  other thread.   And unless they're
  4229.             local variables,  the values will not be snapshotted when
  4230.             the here  document thread  is created.   If  the  current
  4231.             thread (or any other thread) continues to make changes to
  4232.             a variable  after the here document thread is spawned but
  4233.             before it  evaluates the variable, the here document will
  4234.             contain the new, not the old value.]
  4235.  
  4236.                Command   and   variable   substitution   and   escape
  4237.             processing inside  a here  document is  turned off if any
  4238.             part of the end-of-data string following the << is quoted
  4239.             (with single, double or backquotes) or escaped:
  4240.  
  4241.                  115 D% cat <<^***
  4242.                  116 D? The ^$home directory is $home.
  4243.                  117 D? Today's date is `date`.
  4244.                  118 D? ***
  4245.                  The ^$home directory is $home
  4246.                  Today's date is `date`.
  4247.                  119 D% _
  4248.  
  4249.  
  4250.  
  4251.             Inline Data in Scripts
  4252.  
  4253.                Inline data can be especially useful if you're writing
  4254.             a script  file or passing commands to the shell through a
  4255.             pipe.   In either  of these cases, the low-level DosReads
  4256.             to the  OS/2 kernel  (or WriteFiles  to  the  NT  kernel)
  4257.             cannot be  depended on  to stop  at the  end  of  a  line
  4258.             because pipes  and files  are  considered  block-oriented
  4259.             rather than line-oriented like the keyboard.  If too many
  4260.             characters are  read, there's  no simple  way to back up.
  4261.  
  4262.  
  4263.  
  4264.                                      Page 62
  4265.  
  4266.                                                               I/O Redirection
  4267.  
  4268.  
  4269.             For this  reason, it's  not realistic  to write  a script
  4270.             where a  child  process  is  supposed  to  inherit  stdin
  4271.             pointed into  the script file.  In a script file, this is
  4272.             not reliable:
  4273.  
  4274.  
  4275.  
  4276.  
  4277.  
  4278.  
  4279.  
  4280.  
  4281.  
  4282.  
  4283.  
  4284.  
  4285.  
  4286.  
  4287.  
  4288.  
  4289.  
  4290.  
  4291.  
  4292.  
  4293.  
  4294.  
  4295.  
  4296.  
  4297.  
  4298.  
  4299.  
  4300.  
  4301.  
  4302.  
  4303.  
  4304.  
  4305.  
  4306.  
  4307.  
  4308.  
  4309.  
  4310.  
  4311.  
  4312.  
  4313.  
  4314.  
  4315.  
  4316.  
  4317.  
  4318.  
  4319.  
  4320.  
  4321.  
  4322.  
  4323.  
  4324.  
  4325.  
  4326.                                      Page 63
  4327.  
  4328.      I/O Redirection
  4329.  
  4330.  
  4331.                  :
  4332.                  :
  4333.                  csh
  4334.                  echo hello
  4335.                  exit
  4336.                  :
  4337.                  :
  4338.  
  4339.             The file  descriptor  the  child  process  inherits  will
  4340.             likely not  be pointing  at the  ``echo hello'';  when it
  4341.             exits, the  parent will  likely not  find it pointed just
  4342.             past the ``exit''.  This type of script should be written
  4343.             as:
  4344.  
  4345.                  :
  4346.                  :
  4347.                  csh <<eof
  4348.                  echo hello
  4349.                  exit
  4350.                  eof
  4351.                  :
  4352.                  :
  4353.  
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.  
  4361.  
  4362.  
  4363.  
  4364.  
  4365.  
  4366.  
  4367.  
  4368.  
  4369.  
  4370.  
  4371.  
  4372.  
  4373.  
  4374.  
  4375.  
  4376.  
  4377.  
  4378.  
  4379.  
  4380.  
  4381.  
  4382.  
  4383.  
  4384.  
  4385.  
  4386.  
  4387.  
  4388.                                      Page 64
  4389.  
  4390.                                                               I/O Redirection
  4391.  
  4392.  
  4393.             
  4394.  
  4395.  
  4396.  
  4397.  
  4398.  
  4399.  
  4400.  
  4401.  
  4402.  
  4403.  
  4404.  
  4405.  
  4406.  
  4407.  
  4408.  
  4409.  
  4410.  
  4411.  
  4412.  
  4413.  
  4414.  
  4415.  
  4416.  
  4417.  
  4418.  
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.  
  4427.  
  4428.  
  4429.  
  4430.  
  4431.  
  4432.  
  4433.  
  4434.  
  4435.  
  4436.  
  4437.  
  4438.  
  4439.  
  4440.  
  4441.  
  4442.  
  4443.  
  4444.  
  4445.  
  4446.  
  4447.  
  4448.  
  4449.  
  4450.                                      Page 65
  4451.  
  4452.      History
  4453.  
  4454.  
  4455.             
  4456.  
  4457.  
  4458.                               The History Mechanism
  4459.  
  4460.  
  4461.  
  4462.  
  4463.             History
  4464.  
  4465.                The  history  mechanism  lets  you  recall  and  rerun
  4466.             earlier commands.   To see what it's remembered,  use the
  4467.             history command  or its  usual alias  h, which might show
  4468.             you something like the following:
  4469.  
  4470.                  119 D% history 12
  4471.                     108  (this is the inline data)
  4472.                     109  eof
  4473.                     110  end
  4474.                     111  cat << ***
  4475.                     112  The ^$home directory is $home.
  4476.                     113  Today's date is `date`.
  4477.                     114  ***
  4478.                     115  cat << ^***
  4479.                     116  The ^$home directory is $home.
  4480.                     117  Today's date is `date`.
  4481.                     118  ***
  4482.                     119  history 12
  4483.                  120 D% _
  4484.  
  4485.                The history  list won't be quite what you typed: it'll
  4486.             be broken  into separate  words  wherever    one  of  the
  4487.             special tokens,  &, |,  ;, >,  <, (, ), &&, ||, >> or <<,
  4488.             occurs.   Only inline  data escapes  being broken up into
  4489.             words this  way.   Each command  may be  thought of as an
  4490.             array of words, indexed from 0.+
  4491.  
  4492.                To reuse  the text  or maybe  just a  few words from a
  4493.             previous command,  you type  an exclamation point, ``!'',
  4494.             followed by a few characters to identify what you want to
  4495.             reuse.   You can do this anywhere and whatever you select
  4496.             is  just   stuffed  back   on  the  command  line  to  be
  4497.             interpreted  as  whatever  the  context  suggests.    For
  4498.             convenience, the  exclamation point  is not  treated as a
  4499.             history reference  if it's  followed by  white  space  (a
  4500.             space, tab or newline) or by ``='', ``~'' or ``(''.
  4501.  
  4502.  
  4503.  
  4504.             Retrieving a Whole Command Line
  4505.  
  4506.  
  4507.             ____________________
  4508.             + Array indices always start with zero.
  4509.  
  4510.  
  4511.  
  4512.                                      Page 66
  4513.  
  4514.                                                                       History
  4515.  
  4516.  
  4517.                There several ways of picking up a whole command line.
  4518.             You already  know how  to do  it interactively with arrow
  4519.             keys  and  command  completion.    You  can  also  use  a
  4520.             shorthand notation  that can  be more  convenient if  you
  4521.             want to  do something  a bit  more complex.  The simplest
  4522.             shorthand is  ``!!'', which  picks up  the  text  of  the
  4523.             immediately preceding command:
  4524.  
  4525.                  120 D% echo !!
  4526.                  echo history 12
  4527.                  history 12
  4528.                  121 D% !!
  4529.                  echo history 12
  4530.                  history 12
  4531.                  122 D% _
  4532.  
  4533.             The shell  first echoes  your command showing the effects
  4534.             of the  substitutions and  then runs it.  The other quick
  4535.             ways of  referring to  a whole  command line from history
  4536.             are by the command number,
  4537.  
  4538.                  122 D% !96
  4539.                  ls -l  whereis more`
  4540.                  ---A-  Nov 28  16:57   24743  c:\os2\bin\more.exe
  4541.                  ---A-  Oct 21   1987   48354  c:\os2\cmds\more.com
  4542.  
  4543.             relative to the immediately preceding command+,
  4544.  
  4545.                  123 D% echo one
  4546.                  one
  4547.                  124 D% echo two
  4548.                  two
  4549.                  125 D% echo three
  4550.                  three
  4551.                  126 D% !-1
  4552.                  echo two
  4553.                  two
  4554.                  127 D% _
  4555.  
  4556.             or by  mentioning some  of the  text  to  look  for.    A
  4557.             question mark  after the  exclamation point  means you'll
  4558.             accept the  match anywhere  on the line; otherwise it has
  4559.             to be at the start.
  4560.  
  4561.                  128 D% !h
  4562.                  history 12
  4563.                     116  The ^$home directory is $home.
  4564.             ____________________
  4565.             + In this  context, the history list can be thought of as
  4566.               an array  starting with  the zeroth  element being  the
  4567.               immediately preceding command line.  The negative index
  4568.               captures the  notion of  counting backwards in time and
  4569.               differentiates the  syntax from  references by  command
  4570.               number.  See also the bsdhistory variable.
  4571.  
  4572.  
  4573.  
  4574.                                      Page 67
  4575.  
  4576.      History
  4577.  
  4578.  
  4579.                     117  Today's date is `date`.
  4580.                     118  ***
  4581.                     119  history 12
  4582.                     120  echo history 12
  4583.                     121  echo history 12
  4584.                     122  ls -l  `whereis more`
  4585.                     123  echo one
  4586.                     124  echo two
  4587.                     125  echo three
  4588.                     126  echo two
  4589.                     127  history 12
  4590.  
  4591.             A search string ends at the first word boundary.  This is
  4592.             so it's  convenient to  type  additional  text  following
  4593.             without having  it be  confused as  part  of  the  search
  4594.             string.  For example:
  4595.  
  4596.                  128 D% !?one;!?two;!?thr
  4597.                  echo one ; echo two ; echo three
  4598.                  one
  4599.                  two
  4600.                  three
  4601.                  129 D% _
  4602.  
  4603.  
  4604.  
  4605.             Retrieving Individual Words
  4606.  
  4607.                To  pick  off  individual  words  of  the  immediately
  4608.             preceding command,  there's  some  convenient  shorthand.
  4609.             ``!*'' gets all the argument words:
  4610.  
  4611.                  129 D% echo now is the time
  4612.                  now is the time
  4613.                  130 D% echo Finally, !* to begin
  4614.                  echo Finally, now is the time to begin
  4615.                  Finally, now is the time to begin
  4616.                  131 D% _
  4617.  
  4618.             ``!$'' gets just the last word:
  4619.  
  4620.                  131 D% echo the last word was !$.
  4621.                  echo the last word was begin.
  4622.                  the last word was begin.
  4623.                  132 D% _
  4624.  
  4625.             and ``!^'' gets just the first argument word:
  4626.  
  4627.                  132 D% echo ===!^=== time is here
  4628.                  echo ===the=== time is here
  4629.                  ===the=== time is here
  4630.                  133 D% _
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.                                      Page 68
  4637.  
  4638.                                                                       History
  4639.  
  4640.  
  4641.             Notice that  a history  substitution can be smashed right
  4642.             up against other literal text.
  4643.  
  4644.                In the  chapter on  editing, additional facilities for
  4645.             selecting individual words or doing a search/replace will
  4646.             be introduced.
  4647.  
  4648.  
  4649.  
  4650.             History Short-Form
  4651.  
  4652.                Recognizing how  frequently one  would like  to make a
  4653.             simple change  to the  immediately preceding  command  to
  4654.             correct a  typo, the  history mechanism  provides a short
  4655.             form for  just that  purpose.   ``%'' typed  as the first
  4656.             character  on   the  command   line  indicates   that   a
  4657.             search/replace pair follows:
  4658.  
  4659.                  133 D% echo hello world
  4660.                  hello world
  4661.                  134 D% %world%friends%
  4662.                  echo hello friends
  4663.                  hello friends
  4664.  
  4665.                Typing ``%%'' matches the beginning of the line:
  4666.  
  4667.                  135 D% %%echo %
  4668.                  echo echo hello friends
  4669.                  echo hello friends
  4670.  
  4671.                It's also  possible to  refer to  the search string in
  4672.             the replacement  string by  using an  ampersand.    (This
  4673.             example also  illustrates that  the trailing  ``%'' isn't
  4674.             required unless  you want  to explicitly  mark the end of
  4675.             the replacement.)
  4676.  
  4677.                  136 D% %friends%family, & and neighbors
  4678.                  echo echo hello family, friends and neighbors
  4679.                  echo hello family, friends and neighbors
  4680.                  137 D% _
  4681.  
  4682.                Obviously, that raises the question:  how do you put a
  4683.             literal ampersand  in the  replacement?   Simple.    Just
  4684.             quote it with ``^'', the shell escape character.
  4685.  
  4686.                  137 D% %and%^&
  4687.                  echo hello family, friends & neighbors
  4688.                  hello family, friends & neighbors
  4689.                  138 D% _
  4690.  
  4691.  
  4692.  
  4693.  
  4694.  
  4695.  
  4696.  
  4697.  
  4698.                                      Page 69
  4699.  
  4700.      Variables
  4701.  
  4702.  
  4703.             
  4704.  
  4705.  
  4706.                                     Variables
  4707.  
  4708.  
  4709.                As with  any conventional  programming  language,  the
  4710.             shell  provides   a  facility   for  storing   values  in
  4711.             variables.
  4712.  
  4713.  
  4714.  
  4715.             Environmental Variables
  4716.  
  4717.                Some of  the variables  are part  of the  environment,
  4718.             passed along  to any child process or screen group.  Many
  4719.             of the  environment variables will have been created just
  4720.             this way,  e.g., set  to a  value passed  along when  you
  4721.             start the  C shell  from Group  Main  (on  OS/2)  or  the
  4722.             Program  Manager  (on  NT).    To  list  those  currently
  4723.             defined, use  the  setenv  command.    (If  you're  using
  4724.             Windows NT, mentally edit this example to imagine it says
  4725.             nt everywhere you see os2.)
  4726.  
  4727.                  138 D% setenv
  4728.                  COMSPEC      c:\os2\cmd.exe
  4729.                  COLORS       white on blue
  4730.                  DPATH
  4731.                  c:\os2;c:\os2\system;c:\os2\install;c:\;
  4732.                  HOME         d:\doug
  4733.                  INCLUDE      c:\os2\include
  4734.                  LIB          c:\os2\lib
  4735.                  PATH         .;c:\os2\bin;c:\os2\cmds;c:\os2
  4736.                  PROMPT       $iOS/2 $n$g
  4737.                  PROMPT1      $@ $CDISK%
  4738.                  PROMPT2      $@ $CDISK?
  4739.                  SHELL        c:\os2\bin\csh.exe
  4740.                  TABS         3
  4741.                  TMP          e:\tmp
  4742.  
  4743.                Variable names  are case-sensitive  on OS/2  but case-
  4744.             insensitive on  NT.   They can be of arbitrary length.  A
  4745.             name must  start with  an upper- or lower-case alphabetic
  4746.             character  or  underscore  (``_'')  or  at-sign  (``@'');
  4747.             remaining characters  may any of these or decimal digits.
  4748.             Many  of   the  environmental   variables  have  specific
  4749.             meanings.   For example, the PATH variable tells where to
  4750.             look for  executable files,  etc.  Details describing the
  4751.             meaning of  each  variable  are  given  in  the  language
  4752.             reference section.
  4753.  
  4754.                The setenv  command can  also be  used to create a new
  4755.             environmental variable  or alter  or display the value of
  4756.             an existing one:
  4757.  
  4758.  
  4759.  
  4760.                                      Page 70
  4761.  
  4762.                                                                     Variables
  4763.  
  4764.  
  4765.                  139 D% setenv zork = this is the zork variable
  4766.                  140 D% setenv zork
  4767.                  zork         this is the zork variable
  4768.                  141 D% _
  4769.  
  4770.                If the  list of  words being  assigned to the variable
  4771.             includes any special tokens, it's often useful to use the
  4772.             parenthesized variant  of setenv.   In  this example, the
  4773.             ``>'' would  have been  confused as an i/o redirection if
  4774.             it  weren't   inside  parenthesis.     Notice   that  the
  4775.             parenthesis are  stripped off  before the  assignment  is
  4776.             made.
  4777.  
  4778.                  141 D% setenv greatest = (At Berkeley, they say 4.3
  4779.                  > V)
  4780.                  142 D% setenv greatest
  4781.                  greatest     At Berkeley, they say 4.3 > V
  4782.  
  4783.                Even though  the special  meaning is lost, text inside
  4784.             the parenthesis is still broken down into words, as shown
  4785.             in this example:
  4786.  
  4787.                  143 D% setenv pdirs =
  4788.                  (.;c:\os2\bin;c:\os2\cmds;c:\os2;)
  4789.                  144 D% setenv pdirs
  4790.                  pdirs        . ; c:\os2\bin ; c:\os2\cmds ; c:\os2
  4791.  
  4792.                (To avoid  having the  text broken  up into words, use
  4793.             single or double quotes around the string instead.)
  4794.  
  4795.  
  4796.  
  4797.             Set Variables
  4798.  
  4799.                Set variables do not get passed to a child process but
  4800.             are shared  among all  threads.   To get  a list of those
  4801.             currently defined, use the set command:
  4802.  
  4803.                  145 D% set
  4804.                  CDISK        D
  4805.                  argv
  4806.                  cdhome       0
  4807.                  cdisk        d
  4808.                  :
  4809.                  :
  4810.                  path         . c:\os2\bin c:\os2\cmds c:\os2
  4811.                  precision    6
  4812.                  :
  4813.                  :
  4814.  
  4815.                Some  of   the  set   variables  are   linked  to  the
  4816.             environmental variables:  you change  one, and  the other
  4817.             changes  too.    For  example,  path  contains  the  same
  4818.  
  4819.  
  4820.  
  4821.  
  4822.                                      Page 71
  4823.  
  4824.      Variables
  4825.  
  4826.  
  4827.             information as  PATH but,  because it's  been parsed into
  4828.             individual words, it's often a bit more useful.
  4829.  
  4830.                On NT,  this linkage  can pose  a bit  of  a  problem.
  4831.             Since  the   convention  on   NT  is  that  environmental
  4832.             variables are  supposed  to  be  case-insensitive,  there
  4833.             clearly is  a conflict  between, for  example,  the  PATH
  4834.             environmental and  path  set  variables.    The  C  shell
  4835.             resolves this  by making  the set, unset and @ statements
  4836.             case-sensitive (so  you can  still create  set  variables
  4837.             that differ  from environmental  variables only  by case)
  4838.             but the  setenv and  unsetenv and $var and other variable
  4839.             references   first    try   case-sensitive,   then   case
  4840.             insensitive variable lookups.
  4841.  
  4842.                Many of the set variables are pre-defined by the shell
  4843.             to control  various aspects  of how  errors are  handled,
  4844.             etc.   In some cases, each thread maintains its own copy.
  4845.             For example,  it wouldn't  do to  insist that all threads
  4846.             must use  the same  value for  the cwd  (current  working
  4847.             directory)  variable!     The   rest  of  the  variables,
  4848.             including any  defined by  the user, are shared among all
  4849.             threads:   if one  thread changes  a value, all the other
  4850.             threads see  the change immediately.  As we'll see later,
  4851.             this  has  some  implications  when  spawning  background
  4852.             activities.
  4853.  
  4854.                In other respects, set works just like setenv:
  4855.  
  4856.                  146 D% set privatezork = this is the private zork
  4857.                  variable
  4858.                  147 D% set privatezork
  4859.                  privatezork   this is the private zork variable
  4860.                  148 D% _
  4861.  
  4862.                Once a variable has been created as either a set or an
  4863.             environmental variable,  it stays that way:  to change it
  4864.             from  set   to  environmental,   you  must   first  unset
  4865.             (unsetenv) it, then redefine it.
  4866.  
  4867.  
  4868.  
  4869.             Local Variables
  4870.  
  4871.                We just  mentioned that  not all  the pre-defined  set
  4872.             variables are  shared.   Individual threads get their own
  4873.             private copies  of some  because to do otherwise wouldn't
  4874.             be sensible.  Sometimes you need the same sort of control
  4875.             over the variables you create.  You don't want to share a
  4876.             variable with other threads or even with commands outside
  4877.             a very narrow context.
  4878.  
  4879.                You accomplish  this making  the variable local, which
  4880.             means it's  hidden from  outer control  blocks  or  other
  4881.  
  4882.  
  4883.  
  4884.                                      Page 72
  4885.  
  4886.                                                                     Variables
  4887.  
  4888.  
  4889.             threads.   Local variables are really important, as we'll
  4890.             see later, for recursive procedures or for procedures you
  4891.             want to  use from multiple threads.  To define a variable
  4892.             as local,  use the local statement, which accepts a list,
  4893.             separated with commas, of all the variable names you want
  4894.             to be  local.   When a new local variable is created, its
  4895.             initial value  is always null (zero words), even if there
  4896.             was a  previous definition.   Here  you can  see how  the
  4897.             variable i  is redefined inside the nested statements but
  4898.             once you  exit from the nest, the old value of i is again
  4899.             visible:
  4900.  
  4901.                  148 D% set i = hello world
  4902.                  149 D% echo $i
  4903.                  hello world
  4904.                  150 D% (local i; echo $i; set i = how are you; echo
  4905.                  $i)
  4906.                  
  4907.                  how are you
  4908.                  151 D% echo $i
  4909.                  hello world
  4910.  
  4911.                When you  spawn a  child thread, e.g., as a background
  4912.             activity or  as  the  second  or  following  stage  of  a
  4913.             pipeline, it  gets copies  of all  your local  variables,
  4914.             snapshotted at  the time  it's spawned.   If  either  the
  4915.             parent or  the child  later changes  to the  value of any
  4916.             those local variables, they affect only it's own copy.
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.  
  4923.  
  4924.  
  4925.  
  4926.  
  4927.  
  4928.  
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.  
  4939.  
  4940.  
  4941.  
  4942.  
  4943.  
  4944.  
  4945.  
  4946.                                      Page 73
  4947.  
  4948.      Variables
  4949.  
  4950.  
  4951.             Variable Substitutions
  4952.  
  4953.                The simplest  way to  use a  variable is  in a  simple
  4954.             substitution, where  a dollar  sign is  used to  indicate
  4955.             that a variable name follows.   (Similar to using a ``%''
  4956.             in cmd.exe.)    The  value  is  substituted  in  and  the
  4957.             statement is evaluated.
  4958.  
  4959.                  152 D% echo $HOME
  4960.                  d:\doug
  4961.  
  4962.                Text surrounding  the variable  reference is generally
  4963.             just pasted around the value that's substituted in:
  4964.  
  4965.                  153 D% echo My home directory is ---$HOME---
  4966.                  My home directory is ---d:\doug---
  4967.  
  4968.                If the  surrounding text  would be confused as part of
  4969.             the  variable   name,  it's  necessary  to  insulate  the
  4970.             variable reference with braces.  For example:
  4971.  
  4972.                  154 D% echo ${HOME}XXX
  4973.                  d:\dougXXX
  4974.  
  4975.  
  4976.  
  4977.             nonovar
  4978.  
  4979.                If you  try to  reference a  variable, procedure or an
  4980.             alias and  it doesn't  exist, it's  considered  an  error
  4981.             unless you  set the  nonovar variable to indicate how you
  4982.             want the situation treated.
  4983.  
  4984.                  155 D% echo $nonesuch
  4985.                  csh:  The variable 'nonesuch' is not defined.  To
  4986.                  suppress this error, set nonovar = 1 (pass through)
  4987.                  or 2 (discard).
  4988.                  156 D% set nonovar = 1
  4989.                  157 D% !e
  4990.                  echo $nonesuch
  4991.                  $nonesuch
  4992.                  158 D% set nonovar = 2
  4993.                  159 D% !e
  4994.                  echo $nonesuch
  4995.                  
  4996.                  160 D% set nonovar = 0
  4997.  
  4998.  
  4999.  
  5000.             How Variables are Stored
  5001.  
  5002.                Each variable  is kept internally as a list (an array)
  5003.             of objects.   An  individual object  can be  a  (possibly
  5004.             null) character  string, a  32-bit integer  or  a  64-bit
  5005.  
  5006.  
  5007.  
  5008.                                      Page 74
  5009.  
  5010.                                                                     Variables
  5011.  
  5012.  
  5013.             floating point  value.    Generally  speaking,  it's  not
  5014.             necessary to  worry too  much about how a specific object
  5015.             is represented,  though, since  the  shell  automatically
  5016.             does any  necessary conversions  to allow  a value  to be
  5017.             used sensibly in any given context.
  5018.  
  5019.                Notice, however,  that even  though the  value  of  an
  5020.             environmental variable  may  be  a  list,  it  is  always
  5021.             rendered as a simple character string when it's passed to
  5022.             a child  process.   Here's an  example using  the  ``$#''
  5023.             notation to ask how many words are in a variable's value:
  5024.  
  5025.                  161 D% echo $zork
  5026.                  this is the zork variable
  5027.                  162 D% echo $#zork
  5028.                  5
  5029.                  163 D% csh
  5030.                  Hamilton C shell(tm) Release 2.2
  5031.                  Copyright (c) 1988-1993 by Hamilton Laboratories.
  5032.                  All rights reserved.
  5033.                  1 D% echo $zork
  5034.                  this is the zork variable
  5035.                  2 D% echo $#zork
  5036.                  1
  5037.                  3 D% exit
  5038.                  164 D% _
  5039.  
  5040.             In this example, zork holds five words: ``this,'' ``is,''
  5041.             ``the,'' ``zork,''  and ``variable.''   But when we start
  5042.             up a  new child  process running  the  shell,  the  child
  5043.             process sees  zork as holding only a single word:  ``this
  5044.             is the zork variable''.
  5045.  
  5046.                Here's another  example where  we  assign  a  floating
  5047.             point value to an environmental variable.  In the current
  5048.             process, the  exact  binary  floating  representation  is
  5049.             used.   When it's passed to a child process, the value is
  5050.             first converted to a character string, losing some of the
  5051.             precision.     This  example  also  introduces  the  calc
  5052.             statement which  evaluates an  expression and  prints the
  5053.             value.   In an  expression, a variable name is recognized
  5054.             even without a ``$'' to introduce it; in fact, that's the
  5055.             preferable way  to do  it.   If  you  use  a  ``$''-style
  5056.             variable substitution,  the shell  pastes in a character-
  5057.             string representation, again losing precision.  Also, the
  5058.             full  range   of  C   language  expression  operators  is
  5059.             available.
  5060.  
  5061.                  164 D% setenv envVar = 0
  5062.                  165 D% calc ++envVar
  5063.                  1
  5064.                  166 D% calc envVar /= 7
  5065.                  0.142857
  5066.                  167 D% calc envVar*7
  5067.  
  5068.  
  5069.  
  5070.                                      Page 75
  5071.  
  5072.      Variables
  5073.  
  5074.  
  5075.                  1.000000
  5076.                  168 D% csh <<eof
  5077.                  169 D? calc envVar*7
  5078.                  170 D? exit
  5079.                  171 D? eof
  5080.                  Hamilton C shell(tm) Release 2.2
  5081.                  Copyright (c) 1988-1993 by Hamilton Laboratories.
  5082.                  All rights reserved.
  5083.                  0.999999
  5084.                  172 D% calc $envVar*7
  5085.                  0.999999
  5086.  
  5087.  
  5088.  
  5089.             Arrays
  5090.  
  5091.                Variables can  hold a  list of  values indexed  as  an
  5092.             array.   As with  the C  language,  arrays  are  indexed,
  5093.             counting from  zero, with  an expression inside ``[...]''
  5094.             brackets.  The expression can be arbitrarily complex, but
  5095.             it must  evaluate to  an exact  integer value.   The next
  5096.             example shows how a floating point value can be used, but
  5097.             if it's  not precisely an integer, an error results.  The
  5098.             precision variable controls the number of digits past the
  5099.             decimal point  used  when  displaying  a  floating  point
  5100.             value; the maximum is 17 digits.
  5101.  
  5102.                  173 D% set x = now is the time for all good men
  5103.                  174 D% calc x[5.000000]
  5104.                  all
  5105.                  175 D% calc 2**500
  5106.                  3.27339061e+150
  5107.                  176 D% calc y = log2(!$)/100
  5108.                  calc y = log2 ( 2**500 ) /100
  5109.                  5.000000
  5110.                  177 D% calc x[y]
  5111.                  csh:  Couldn't evaluate the index to the variable
  5112.                  'x'.
  5113.                  178 D% set precision = 30
  5114.                  179 D% calc precision
  5115.                  17
  5116.                  180 D% calc y
  5117.                  5.00000000000000100
  5118.                  181 D% calc x[round(y)]
  5119.                  all
  5120.  
  5121.                An array  cannot be  ``sparse;'' i.e.,  before you can
  5122.             create an element 5, element 4 must exist and so on.  But
  5123.             it's perfectly legal to keep adding new elements onto the
  5124.             end of  array as  long as  the new  element is the zeroth
  5125.             element or  only one  past whatever's  currently the last
  5126.             element.   Here's an  example using  a for  loop.   The @
  5127.             statement is like calc except it doesn't print anything.
  5128.  
  5129.  
  5130.  
  5131.  
  5132.                                      Page 76
  5133.  
  5134.                                                                     Variables
  5135.  
  5136.  
  5137.                  182 D% unset x
  5138.                  183 D% for i = 0 to 4 do
  5139.                  184 D? @ x[i] = 2*i
  5140.                  185 D? end
  5141.                  186 D% echo $x
  5142.                  0 2 4 6 8
  5143.  
  5144.  
  5145.  
  5146.             nullwords
  5147.  
  5148.                When you  index an  array, if  the element you specify
  5149.             doesn't exist,  that's normally considered an error.  For
  5150.             example, x  contains 5 words; trying to reference a sixth
  5151.             fails:
  5152.  
  5153.                  187 D% calc x[5]
  5154.                  csh:  Illegal subscript in variable reference
  5155.                  'x[5]'.  (To suppress this error, set nullwords =
  5156.                  1.)
  5157.  
  5158.                The nullwords  variable is used to tell the shell that
  5159.             you'd like  to ignore subscripting errors when you try to
  5160.             evaluate a  variable reference.   nullwords has no effect
  5161.             over subscripting errors when you try to set the value of
  5162.             a non-existent element.  Here are some examples:
  5163.  
  5164.                  188 D% set nullwords = 1
  5165.                  189 D% echo -- "--->$x[999]<---"
  5166.                  ---><---
  5167.                  190 D% calc x[999] = "does not work"
  5168.                  csh:  Illegal subscript in variable reference
  5169.                  'x[999]'.
  5170.  
  5171.             The use  of the  ``--'' option  and of  double quotes was
  5172.             important:   ``--'' told echo that it had reached the end
  5173.             of any options, allowing it to print something that began
  5174.             with a  minus sign.   The  quotes were used, in the first
  5175.             case, to  turn off  recognition of redirection characters
  5176.             ``>'' and  ``<'' but still get the variable substitution.
  5177.             The second  time, it  was to  make the string, ``does not
  5178.             work'' a single word.  (If you try leaving off the quotes
  5179.             or not  using ``--,''  you'll see that the error messages
  5180.             are what you'd expect.)
  5181.  
  5182.  
  5183.  
  5184.  
  5185.  
  5186.  
  5187.  
  5188.  
  5189.  
  5190.  
  5191.  
  5192.  
  5193.  
  5194.                                      Page 77
  5195.  
  5196.      Variables
  5197.  
  5198.  
  5199.             
  5200.  
  5201.  
  5202.  
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.  
  5209.  
  5210.  
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.  
  5219.  
  5220.  
  5221.  
  5222.  
  5223.  
  5224.  
  5225.  
  5226.  
  5227.  
  5228.  
  5229.  
  5230.  
  5231.  
  5232.  
  5233.  
  5234.  
  5235.  
  5236.  
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.  
  5247.  
  5248.  
  5249.  
  5250.  
  5251.  
  5252.  
  5253.  
  5254.  
  5255.  
  5256.                                      Page 78
  5257.  
  5258.                                                                   Wildcarding
  5259.  
  5260.  
  5261.             
  5262.  
  5263.  
  5264.                                    Wildcarding
  5265.  
  5266.  
  5267.                The notion  of wildcarding is pretty simple:  the user
  5268.             gives just  a few characters describing the filename he's
  5269.             looking  for   and  system  fills  in  the  rest.    With
  5270.             ``vanilla'' OS/2 or NT, wildcarding is the responsibility
  5271.             of each  application, based on the command-line arguments
  5272.             it's given.  Typically, the application designer fulfills
  5273.             this by linking in a library routine which does a simple-
  5274.             minded half-hearted wildcarding.
  5275.  
  5276.                Hamilton C  shell does the wildcarding before invoking
  5277.             the application.   The  shell's wildcarding includes five
  5278.             components:     home  directory   expansion,  wildcarding
  5279.             characters,   ranges,    alternation    and    indefinite
  5280.             directories.   A powerful  recursive match  algorithm  is
  5281.             employed to  guarantee a  sensible result  no matter  how
  5282.             complex the pattern.
  5283.  
  5284.  
  5285.  
  5286.             Home Directory Expansion
  5287.  
  5288.                The tilde character, ``~'', is recognized as shorthand
  5289.             for the home directory.  In the simplest form, we can use
  5290.             it just by itself:
  5291.  
  5292.                  191 D? echo $home
  5293.                  d:\doug
  5294.                  192 D% cd ~
  5295.                  193 D% cd
  5296.                  d:\doug
  5297.  
  5298.                There's also shorthand for children or siblings of the
  5299.             home directory:
  5300.  
  5301.                  194 D% cd ~\samples
  5302.                  195 D% cd
  5303.                  d:\doug\samples
  5304.                  196 D% cd ~carol
  5305.                  197 D% cd
  5306.                  d:\carol
  5307.  
  5308.  
  5309.  
  5310.             Wildcard Characters
  5311.  
  5312.                The wildcard  characters,  ``*''  and  ``?'',  provide
  5313.             shorthand for ``match any string'' and ``match any single
  5314.             character,'' respectively.
  5315.  
  5316.  
  5317.  
  5318.                                      Page 79
  5319.  
  5320.      Wildcarding
  5321.  
  5322.  
  5323.                Suppose the  home directory  contained  the  following
  5324.             contents:
  5325.  
  5326.                  198 D% cd ~
  5327.                  199 D% ls
  5328.  
  5329.  
  5330.  
  5331.  
  5332.  
  5333.  
  5334.  
  5335.  
  5336.  
  5337.  
  5338.  
  5339.  
  5340.  
  5341.  
  5342.  
  5343.  
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.  
  5351.  
  5352.  
  5353.  
  5354.  
  5355.  
  5356.  
  5357.  
  5358.  
  5359.  
  5360.  
  5361.  
  5362.  
  5363.  
  5364.  
  5365.  
  5366.  
  5367.  
  5368.  
  5369.  
  5370.  
  5371.  
  5372.  
  5373.  
  5374.  
  5375.  
  5376.  
  5377.  
  5378.  
  5379.  
  5380.                                      Page 80
  5381.  
  5382.                                                                   Wildcarding
  5383.  
  5384.  
  5385.                  bcs         mandel      sh          ex.rc
  5386.                  release.csh
  5387.                  bix         mba         testcode    icon.ico
  5388.                  ring.ico
  5389.                  channel.one online      util        login.csh
  5390.                  snapshot.csh
  5391.                  dial        postscpt    word        mail
  5392.                  startup.csh
  5393.                  excel       regressn    backup.csh  os2init.cmd
  5394.                  vi.ini
  5395.                  games       resume      brite.csh   popup.txt
  5396.                  icon        samples     class.txt   prime.c
  5397.  
  5398.                The following  example shows the use of ``?'' to match
  5399.             any single  character.  Wildcard results are always shown
  5400.             alphabetically in  lower case.   No  distinction is  made
  5401.             between directories and files.
  5402.  
  5403.                  200 D% echo ????
  5404.                  dial icon mail util word
  5405.                  201 D% echo b??
  5406.                  bcs bix
  5407.  
  5408.                The ``*''  can match zero or more arbitrary characters
  5409.             except  ``:''   or  ``\'';   in  contrast   to  DOS-style
  5410.             wildcarding,  ``*''  can  match  ``.''.    If  there  are
  5411.             ordinary characters  in the  pattern, they  must also  be
  5412.             matched.
  5413.  
  5414.                  202 D% echo *mp*e*
  5415.                  samples
  5416.  
  5417.                Because the  wildcarding is done before the command is
  5418.             invoked  (without   the  command   even   being   aware),
  5419.             wildcarding can even be done on a cd command:
  5420.  
  5421.                  203 D% cd !$
  5422.                  cd *mp*e*
  5423.                  204 D% cd
  5424.                  d:\doug\samples
  5425.  
  5426.                Wildcarding is  most emphatically  not  restricted  to
  5427.             matches only against a single directory level.  Here's an
  5428.             example that  wildcards across  all  the  subdirectories,
  5429.             looking for .c files that begin with ``a''.
  5430.  
  5431.                  205 D% cd ..
  5432.                  206 D% echo *\a*.c
  5433.                  samples\args.c sh\allocate.c
  5434.  
  5435.                Wildcarding can  even be  done  against  driveletters.
  5436.             For example:
  5437.  
  5438.  
  5439.  
  5440.  
  5441.  
  5442.                                      Page 81
  5443.  
  5444.      Wildcarding
  5445.  
  5446.  
  5447.                  207 D% echo *:\*\q*
  5448.                  i:\mail\quotes.doc i:\tmp\query.out
  5449.                  j:\doug\quantity.disc
  5450.  
  5451.             When  wildcarding   against   driveletters,   the   shell
  5452.             restricts the  set of  drives it will search down to just
  5453.             those specified  by the  DRIVEMASK environment  variable.
  5454.             If you  don't specify  a DRIVEMASK,  the default  is  all
  5455.             drives except  the floppies  a: and  b:.   The search  is
  5456.             restricted so  you don't waste time trying to access slow
  5457.             removable media that may not even be ready.
  5458.  
  5459.  
  5460.  
  5461.             Ranges
  5462.  
  5463.                Ranges describe  a set of characters, any one of which
  5464.             will be  matched.  It's specified as a list of acceptable
  5465.             characters inside ``[...]'' brackets.  The range ``[be]''
  5466.             means either  ``b'' or  ``e''; ``[b-e]'' is shorthand for
  5467.             any  character  in  the  sequence  ``b''  through  ``e''.
  5468.             Within the  brackets, any  number of hyphenated sequences
  5469.             and single  characters can  pasted one after the other in
  5470.             any order.   For example, ``[a-cu-zgkmp]'' is a perfectly
  5471.             legal range.   Here  are a  couple examples.  Notice that
  5472.             ranges can also be used with driveletters.
  5473.  
  5474.                  208 D% echo [be]*
  5475.                  backup.csh bcs bix brite.csh ex.rc excel
  5476.                  209 D% echo[d-g]:\[s-t]*
  5477.                  d:\taxes d:\tmp e:\spool e:\startup.cmd e:\temp
  5478.                  e:\toolkit.sys f:\swap f:\tmp f:\toys g:\skip
  5479.                  g:\temp g:\tmp
  5480.  
  5481.                An exclusion  range is  written as a set of characters
  5482.             inside the brackets that starts with a circumflex.  It'll
  5483.             match any single character not in the range.
  5484.  
  5485.                  210 D% echo [^a-t]*
  5486.                  util vi.ini word
  5487.  
  5488.  
  5489.  
  5490.             Alternation
  5491.  
  5492.                Alternation, specified  with ``{...}''  braces,  is  a
  5493.             shorthand way  of specifying that all the combinations of
  5494.             frontparts and backparts should be generated. There isn't
  5495.             any requirement  that the  filenames constructed actually
  5496.             exist.
  5497.  
  5498.                  211 D% echo {zork,gadzooks}.csh
  5499.                  zork.csh gadzooks.csh
  5500.  
  5501.  
  5502.  
  5503.  
  5504.                                      Page 82
  5505.  
  5506.                                                                   Wildcarding
  5507.  
  5508.  
  5509.                  212 D% echo {a,b}{c,d}{e,f}
  5510.                  ace acf ade adf bce bcf bde bdf
  5511.  
  5512.                Alternation can be combined arbitrarily with the other
  5513.             wildcard constructs:
  5514.  
  5515.                  213 D% echo {[bc],*r}*i*
  5516.                  bix brite.csh brite.csh ring.ico
  5517.  
  5518.  
  5519.  
  5520.             Indefinite Directories
  5521.  
  5522.                The  ellipsis,  ``...'',  is  an  indefinite  definite
  5523.             directory wildcard.   It'll  match zero or more arbitrary
  5524.             directory levels -- whatever it takes to make the rest of
  5525.             the wildcard  match.  To be recognized as a wildcard, the
  5526.             context must  indicate it's  really a  filename, i.e., it
  5527.             must be  preceded by  ``\'', ``/'',  ``~''  or  ``:''  or
  5528.             followed by ``\'' or ``/''.  For example, to find all the
  5529.             .inf files anywhere on the C: drive, one might type:
  5530.  
  5531.                  214 D% ls c:\...\*.inf
  5532.                  c:\os2\book\cmdref.inf
  5533.  
  5534.                As with  all the  wildcard constructs,  the indefinite
  5535.             directory construct  can be  used completely arbitrarily.
  5536.             It can  even be  used several times in the same wildcard.
  5537.             But do  notice if  you do that, there is a possibility of
  5538.             getting the same file listed more than once:
  5539.  
  5540.                  215 D% ls f:\...\a*\...\money*
  5541.                  f:\os2\aldus\art\moneycht.eps
  5542.                  f:\os2\aldus\art\moneycht.eps
  5543.  
  5544.                This can  happen if there's more than one possible way
  5545.             to match  the same pathname.  In this example, the ``a*''
  5546.             part could  matched either  ``aldus'' or ``art'' with the
  5547.             first ``...''  matching either  ``os2\aldus'' or  ``os2''
  5548.             and the  second ``...''  matching either  ``art'' or just
  5549.             zero levels.
  5550.  
  5551.  
  5552.  
  5553.             Match Failures
  5554.  
  5555.                When you  specify a  sequence of wildcard patterns and
  5556.             none of  them match,  it's normally  treated as an error.
  5557.             In this  example,  the  first  command  causes  an  error
  5558.             because there's no file or directory name with a ``z'' in
  5559.             it.   The second  command executes without error because,
  5560.             out of  the sequence  of patterns,  there's at  least one
  5561.             match.
  5562.  
  5563.  
  5564.  
  5565.  
  5566.                                      Page 83
  5567.  
  5568.      Wildcarding
  5569.  
  5570.  
  5571.                  216 D% echo *z*
  5572.                  csh:  Wildcarding failed to produce any matches.  To
  5573.                  suppress this error, set nonomatch = 1 (pass
  5574.                  through) or 2 (discard).
  5575.                  217 D% echo *z* sa*
  5576.                  samples
  5577.  
  5578.                In this  context, the  fact  that  alternation  caused
  5579.             something to be generated is not the same as a match.  In
  5580.             the next example, ``{zork,gadzooks,*z*}.csh'' is the same
  5581.             as  ``zork.csh  gadzooks.csh  *z*.csh'';  only  the  last
  5582.             element involves any matching, and it fails.
  5583.  
  5584.                  218 D% echo {zork,gadzooks,*z*}.csh
  5585.                  csh:  Wildcarding failed to produce any matches.  To
  5586.                  suppress this error, set nonomatch = 1 (pass
  5587.                  through) or 2 (discard).
  5588.  
  5589.                The nonomatch variable lets you control how a wildcard
  5590.             failure is  treated.  It works just the way nonovar works
  5591.             when you reference to a non-existent variable.
  5592.  
  5593.                  219 D% set nonomatch = 1
  5594.                  220 D% echo *z*
  5595.                  *z*
  5596.                  221 D% !s:s/1/2/
  5597.                  set nonomatch = 2
  5598.                  222 D% !e
  5599.                  echo *z*
  5600.                  
  5601.                  223 D% !s:s/2/0/
  5602.                  set nonomatch = 0
  5603.                  224 D% !e
  5604.                  echo *z*
  5605.                  csh:  Wildcarding failed to produce any matches.  To
  5606.                  suppress this error, set nonomatch = 1 (pass
  5607.                  through) or 2 (discard).
  5608.  
  5609.  
  5610.  
  5611.             Caution:  The copy, xcopy, rename and del commands
  5612.  
  5613.                Hamilton C  shell  expands  out  wildcards  before  it
  5614.             invokes the  application you  name.  This is not what the
  5615.             copy and  xcopy commands  expect!   Suppose there are two
  5616.             files, file.a  and file.b  on your  diskette a:, that you
  5617.             wanted to  copy to your current drive.  Under cmd.exe, it
  5618.             would be natural to type:
  5619.  
  5620.                  [D:\DOUG] xcopy.exe a:*.*
  5621.                  Source files are being read...
  5622.                  
  5623.                  A:FILE.A
  5624.                  A:FILE.B
  5625.  
  5626.  
  5627.  
  5628.                                      Page 84
  5629.  
  5630.                                                                   Wildcarding
  5631.  
  5632.  
  5633.                  
  5634.                  2 file(s) copied.
  5635.  
  5636.                The destination  is implicit.   xcopy  understands the
  5637.             wildcarding to  mean ``copy everything on drive a: to the
  5638.             current disk  and directory.''   That  is not  what would
  5639.             happen under  the C shell!  Because the wildcard would be
  5640.             expanded first, it would act instead as if you had typed:
  5641.  
  5642.                  [D:\DOUG] xcopy.exe a:file.a a:file.b
  5643.                  Source files are being read...
  5644.                  
  5645.                  A:FILE.A
  5646.                  
  5647.                  1 file(s) copied.
  5648.  
  5649.                Do you  see what  happens?   If  wildcarding  is  done
  5650.             first, the  xcopy command sees just the two filenames and
  5651.             figures you  mean to  copy  one  right  over  the  other.
  5652.             file.b is  lost!  For this reason, the normal startup.csh
  5653.             file contains  some  carefully  constructed  aliases  and
  5654.             procedures to  intercept the  copy, xcopy, rename and del
  5655.             commands:
  5656.  
  5657.                  proc safecopy(files)
  5658.                     cmd /c copy $files; @ nowild = s; unlocal s
  5659.                  end
  5660.                  alias copy   (local s; @ s = nowild; @ nowild = 1;
  5661.                  safecopy)
  5662.                  
  5663.                  proc safexcopy(files)
  5664.                     xcopy.exe $files; @ nowild = s; unlocal s
  5665.                  end
  5666.                  alias xcopy  (local s; @ s = nowild; @ nowild = 1;
  5667.                  safexcopy)
  5668.                  
  5669.                  proc saferename(files)
  5670.                     cmd /c rename $files; @ nowild = s; unlocal s
  5671.                  end
  5672.                  alias rename (local s; @ s = nowild; @ nowild = 1;
  5673.                  saferename)
  5674.                  alias ren    rename
  5675.                  
  5676.                  proc safedel(files)
  5677.                     cmd /c del $files; @ nowild = s; unlocal s
  5678.                  end
  5679.                  alias del      (local s; @ s = nowild; @ nowild = 1;
  5680.                  safedel)
  5681.                  alias erase    del
  5682.  
  5683.                The way  this works  by saving  the current  value  of
  5684.             nowild (which  tells whether  wildcarding  is  should  be
  5685.             done),   turning    off   wildcarding,    invoking    the
  5686.             copy/xcopy/rename/del   command,   then   restoring   the
  5687.  
  5688.  
  5689.  
  5690.                                      Page 85
  5691.  
  5692.      Wildcarding
  5693.  
  5694.  
  5695.             wildcarding state.   s  is a temporary variable that gets
  5696.             discarded after its been used.
  5697.  
  5698.                Be sure  to always  invoke copy,  xcopy rename and del
  5699.             via these  aliases.   If you encounter other applications
  5700.             that really  must do their own wildcarding, use this same
  5701.             technique with them.
  5702.  
  5703.  
  5704.  
  5705.  
  5706.  
  5707.  
  5708.  
  5709.  
  5710.  
  5711.  
  5712.  
  5713.  
  5714.  
  5715.  
  5716.  
  5717.  
  5718.  
  5719.  
  5720.  
  5721.  
  5722.  
  5723.  
  5724.  
  5725.  
  5726.  
  5727.  
  5728.  
  5729.  
  5730.  
  5731.  
  5732.  
  5733.  
  5734.  
  5735.  
  5736.  
  5737.  
  5738.  
  5739.  
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.  
  5747.  
  5748.  
  5749.  
  5750.  
  5751.  
  5752.                                      Page 86
  5753.  
  5754.                                                                       Editing
  5755.  
  5756.  
  5757.             
  5758.  
  5759.  
  5760.                                      Editing
  5761.  
  5762.  
  5763.                Often, the  text returned  by a  history, variable  or
  5764.             command substitution  isn't quite  what you  want.    For
  5765.             example, you  may want to select only certain words, do a
  5766.             search/replace, or  manipulate  a  filename  that's  been
  5767.             returned.     The  editing   facilities   provide   these
  5768.             capabilities.
  5769.  
  5770.                The examples  in  this  chapter  show  a  sampling  of
  5771.             various combinations  of editing  commands and  types  of
  5772.             substitutions.   There simply  isn't room to show all the
  5773.             possibilities nor  is there  really a  need to:  with two
  5774.             exceptions (``:%''and ``:p''), any editing command can be
  5775.             applied against  any substitution  type  or  against  the
  5776.             result of another editing command.
  5777.  
  5778.  
  5779.  
  5780.             Word Selections
  5781.  
  5782.                Editing modifiers  begin with a colon, ``:'', followed
  5783.             by an  editing command.   You  can select words either by
  5784.             number or symbolically:  first, last, all, etc.  Here are
  5785.             examples of  the ``:*'',  ``:$'' and  ``:^'' modifiers to
  5786.             select all, last, and first argument words, respectively.
  5787.             Notice that  any number  of editing  modifiers may strung
  5788.             together.  For example, ``:*:^'' means the first argument
  5789.             word (word  1) of the sequence formed of all the original
  5790.             argument words: i.e., word 2.
  5791.  
  5792.                  225 D% echo Finally, now is the time
  5793.                  Finally, now is the time
  5794.                  226 D% echo !!:$
  5795.                  time
  5796.                  227 D% echo !?Fin:*:^
  5797.                  echo now
  5798.                  now
  5799.  
  5800.                It is  also  possible  to  select  words  by  indexing
  5801.             through the  array associated  with a given substitution.
  5802.             The words are counted from zero.
  5803.  
  5804.                  228 D% echo `echo now is the time`:2
  5805.                  the
  5806.  
  5807.                Ranges of  words can  also be  specified with a hyphen
  5808.             between the  beginning and  ending word indices.  In this
  5809.             context,  the   minus  sign   indicates  a   range,   not
  5810.             subtraction.
  5811.  
  5812.  
  5813.  
  5814.                                      Page 87
  5815.  
  5816.      Editing
  5817.  
  5818.  
  5819.                  229 D% set x = now is the time for all good men
  5820.                  230 D% echo $x:1-5
  5821.                  is the time for all
  5822.  
  5823.                When   the   operand   is   a   ``!?''-style   history
  5824.             substitution, there's  a special  operator,  ``:%'',  for
  5825.             selecting the particular word that triggered the match:
  5826.  
  5827.                  231 D% echo !?Fin:%
  5828.                  echo Finally
  5829.                  Finally
  5830.  
  5831.                Each of  the three  symbolic  word  selectors,  ``^'',
  5832.             ``$'' and  ``%'', can  be used  anywhere a  decimal  word
  5833.             number would be acceptable.  For example:
  5834.  
  5835.                  232 D% echo !?time:%-$
  5836.                  echo time for all good men
  5837.                  time for all good men
  5838.  
  5839.  
  5840.  
  5841.             Search/Replace Operations
  5842.  
  5843.                A search/replace  operation looks  for and  replaces a
  5844.             simple character  string.   (For those familiar with such
  5845.             things, it  does not  use regular  expressions.)   If the
  5846.             search string isn't given, the one used last time is used
  5847.             again.   If the  replace string  contains  an  ampersand,
  5848.             ``&'', that  isn't  escaped  with  the  circumflex,  it's
  5849.             expanded  into  the  search  string.    Here  are  a  few
  5850.             examples.  Notice that putting a ``g'' at the start of an
  5851.             operation makes it ``global.''
  5852.  
  5853.                  233 D% echo !?now:%-$:s/o/O/
  5854.                  echo nOw is the time for all good men
  5855.                  nOw is the time for all good men
  5856.                  234 D% !!:gs/t/T/
  5857.                  echo nOw is The Time for all good men
  5858.                  nOw is The Time for all good men
  5859.                  235 D% !!:s/nOw is/& really/
  5860.                  echo nOw is The Time for all good men
  5861.                  nOw is really The Time for all good men
  5862.  
  5863.  
  5864.  
  5865.             Pathname Editing
  5866.  
  5867.                Another set of operators allows filenames to be easily
  5868.             manipulated.     As  with  the  search/replace  operator,
  5869.             pathname editing  is normally  applied to  only the first
  5870.             operand word;  if you want the operation performed on all
  5871.             the words, you must make it global.  In this example, the
  5872.  
  5873.  
  5874.  
  5875.  
  5876.                                      Page 88
  5877.  
  5878.                                                                       Editing
  5879.  
  5880.  
  5881.             ``:h'' (head) operator is used, which returns the name of
  5882.             the directory containing the given file.
  5883.  
  5884.                  236 D% echo *\a*.c
  5885.                  samples\args.c sh\allocate.c
  5886.                  237 D% set dotc = !$
  5887.                  set dotc = *\a*.c
  5888.                  238 D% echo $dotc
  5889.                  samples\args.c sh\allocate.c
  5890.                  239 D% echo $dotc:h
  5891.                  samples sh\allocate.c
  5892.                  240 D% echo $dotc:gh
  5893.                  samples sh
  5894.  
  5895.  
  5896.  
  5897.             Specialized Operations
  5898.  
  5899.                Specialized operations  are provided  for  scanning  a
  5900.             character string  and  breaking  it  up  into  words  and
  5901.             applying quotes around each word.
  5902.  
  5903.                The ``:x''  operator for  breaking up  a  string  into
  5904.             words is  particularly useful  for parsing text read with
  5905.             the getline  pseudo-variable, which  always  returns  the
  5906.             line read as a single character string:
  5907.  
  5908.                  241 D% @ data = $<
  5909.                  (I typed -->this<-- in)
  5910.                  242 D% echo $#data $data
  5911.                  1 (I typed -->this<-- in)
  5912.                  243 D% set data = $data:x
  5913.                  244 D% echo $#data $data
  5914.                  10 ( I typed -- > this < -- in )
  5915.  
  5916.                The ``:q''  operator pastes  single quote marks around
  5917.             every word  in the  operand list.   As  we'll see  in the
  5918.             chapter on  quoting, this  prevents any further wildcard,
  5919.             variable or command substitutions from being done.
  5920.  
  5921.                  245 D% echo sa?pl?s *\a*.c
  5922.                  samples samples\args.c sh\allocate.c
  5923.                  246 D% echo !*:q
  5924.                  echo 'sa?pl?s' '*\a*.c'
  5925.                  sa?pl?s *\a*.c
  5926.  
  5927.  
  5928.  
  5929.             History Edits
  5930.  
  5931.                For history  substitutions, the ``:p'' operator can be
  5932.             used to  cause the  result of the history substitution to
  5933.             be echoed  and entered  into the history list but for the
  5934.             command not  to be executed.  This is helpful when you're
  5935.  
  5936.  
  5937.  
  5938.                                      Page 89
  5939.  
  5940.      Editing
  5941.  
  5942.  
  5943.             trying a  complicated edit  and not sure if the result is
  5944.             going to be what you want.
  5945.  
  5946.                  247 D% !?Fin:p
  5947.                  echo Finally
  5948.                  248 D% !!
  5949.                  echo Finally
  5950.                  Finally
  5951.                  249 D% _
  5952.  
  5953.  
  5954.  
  5955.  
  5956.  
  5957.  
  5958.  
  5959.  
  5960.  
  5961.  
  5962.  
  5963.  
  5964.  
  5965.  
  5966.  
  5967.  
  5968.  
  5969.  
  5970.  
  5971.  
  5972.  
  5973.  
  5974.  
  5975.  
  5976.  
  5977.  
  5978.  
  5979.  
  5980.  
  5981.  
  5982.  
  5983.  
  5984.  
  5985.  
  5986.  
  5987.  
  5988.  
  5989.  
  5990.  
  5991.  
  5992.  
  5993.  
  5994.  
  5995.  
  5996.  
  5997.  
  5998.  
  5999.  
  6000.                                      Page 90
  6001.  
  6002.                                                                       Editing
  6003.  
  6004.  
  6005.             
  6006.  
  6007.  
  6008.  
  6009.  
  6010.  
  6011.  
  6012.  
  6013.  
  6014.  
  6015.  
  6016.  
  6017.  
  6018.  
  6019.  
  6020.  
  6021.  
  6022.  
  6023.  
  6024.  
  6025.  
  6026.  
  6027.  
  6028.  
  6029.  
  6030.  
  6031.  
  6032.  
  6033.  
  6034.  
  6035.  
  6036.  
  6037.  
  6038.  
  6039.  
  6040.  
  6041.  
  6042.  
  6043.  
  6044.  
  6045.  
  6046.  
  6047.  
  6048.  
  6049.  
  6050.  
  6051.  
  6052.  
  6053.  
  6054.  
  6055.  
  6056.  
  6057.  
  6058.  
  6059.  
  6060.  
  6061.  
  6062.                                      Page 91
  6063.  
  6064.      Quoting
  6065.  
  6066.  
  6067.             
  6068.  
  6069.  
  6070.                                      Quoting
  6071.  
  6072.  
  6073.                The shell has several quoting mechanisms for marking a
  6074.             section of  a command  for special  processing.   One  of
  6075.             them, command  substitution, which used the `...` syntax,
  6076.             was already  discussed in the chapter on i/o redirection;
  6077.             that discussion won't be repeated here.
  6078.  
  6079.                The other  quoting mechanisms focus more simply on the
  6080.             problem of  overriding the  special meanings that certain
  6081.             characters have.
  6082.  
  6083.  
  6084.  
  6085.             Double Quotes
  6086.  
  6087.                Double quotes  are of  use when  you want  to  pass  a
  6088.             character  string   containing  a  space  or  other  word
  6089.             separator to an application.  Normally, if you called a C
  6090.             program, it  would  see  these  words  as  separate  argv
  6091.             entries instead  a single character string; double quotes
  6092.             prevents this  breakup into  words.   We can  demonstrate
  6093.             this using  the simple  myecho  program  in  the  samples
  6094.             directory which prints out the argv list it receives with
  6095.             single quotes around each entry:
  6096.  
  6097.                  249 D% cd ~\samples
  6098.                  250 D% myecho hello world
  6099.                  'myecho' 'hello' 'world'
  6100.                  arg length = 19 characters
  6101.                  251 D% myecho "hello world"
  6102.                  'myecho' 'hello world'
  6103.                  arg length = 19 characters
  6104.  
  6105.                Double quotes also turn off the special meaning of the
  6106.             various wildcard characters and the single quote:
  6107.  
  6108.                  252 D% echo "* isn't a wildcard character inside
  6109.                  quotes"
  6110.                  * isn't a wildcard character inside quotes
  6111.                  253 D% echo "~"
  6112.                  ~
  6113.                  254 D% _
  6114.  
  6115.                Command, history  and  variable  substitutions  inside
  6116.             double quotes are still done:
  6117.  
  6118.                  254 D% echo "*** The home directory is $home ***"
  6119.                  *** The home directory is d:\doug ***
  6120.                  255 D% echo "`echo ~`"
  6121.  
  6122.  
  6123.  
  6124.                                      Page 92
  6125.  
  6126.                                                                       Quoting
  6127.  
  6128.  
  6129.                  d:\doug
  6130.                  256 D% echo "myecho.c is `wc -l < myecho.c` lines
  6131.                  long"
  6132.                  myecho.c is 24 lines long
  6133.                  257 D% echo "!?samples"
  6134.                  echo "cd ~\samples"
  6135.                  cd ~\samples
  6136.  
  6137.  
  6138.  
  6139.             Single Quotes
  6140.  
  6141.                Single quotes  are a  little more  brute force to turn
  6142.             off special  meanings.   Wildcards, variables and command
  6143.             substitutions are  all treated  as ordinary  text.   Only
  6144.             history references are recognized inside single quotes.
  6145.  
  6146.                  258 D% echo '*'
  6147.                  *
  6148.                  259 D% echo '$cwd'
  6149.                  $cwd
  6150.                  260 D% echo '`echo hello`"
  6151.                  `echo hello`
  6152.                  261 D% echo '!?samples'
  6153.                  echo 'echo "cd ~\samples"'
  6154.                  echo "cd ~\samples"
  6155.                  262 D% _
  6156.  
  6157.                It is  not necessary  to quote  an entire  word.  It's
  6158.             possible (and  often useful) to selectively quote just as
  6159.             much as  desired.   The quoting  characters are processed
  6160.             out just before invoking the command.  Example:
  6161.  
  6162.                  263 D% echo 'no'w is "t"h'e' `echo time`
  6163.                  now is the time
  6164.  
  6165.  
  6166.  
  6167.             Shell Escape Character
  6168.  
  6169.                The   shell   escape   character   is   normally   the
  6170.             circumflex+, ``^''.   It  has two uses:  preceding any of
  6171.             the  special   characters,  it  turns  off  that  special
  6172.             meaning.  When followed by an alphabetic character or hex
  6173.             or octal  number, it  can be used to enter binary data or
  6174.             characters that  couldn't easily  be typed.    To  get  a
  6175.  
  6176.             ____________________
  6177.             + The circumflex  was chosen  as the default shell escape
  6178.               character  to  be  consistent  with  OS/2  conventions.
  6179.               Choosing  the   Unix  backslash   instead  would   have
  6180.               conflicted  badly   with  OS/2   filename  conventions.
  6181.               Nonetheless, the  escapesym  variable  does  allow  the
  6182.               adventuresome to make a different choice.
  6183.  
  6184.  
  6185.  
  6186.                                      Page 93
  6187.  
  6188.      Quoting
  6189.  
  6190.  
  6191.             literal escape  character, type  two escapes  in  a  row.
  6192.             These specific escape sequences have special meaning:
  6193.  
  6194.                  ^a   Audible Alert (Bell)     ^r   Carriage Return
  6195.                  ^b   BackSpace                ^t   Tab
  6196.                  ^f   Form Feed                ^v   Vertical Tab
  6197.                  ^n   NewLine                  ^^   Single escapesym
  6198.  
  6199.                At the  very end  of a  line, the escape has a special
  6200.             meaning:  the next line is a continuation line.  Inside a
  6201.             quoted string,  the  ``^''-newline  combination  will  be
  6202.             replaced  with  a  simple  newline;  anywhere  else,  the
  6203.             combination is  just turned  into a  space.    The  other
  6204.             special case is when it immediately follows ``[''.  Since
  6205.             ``[^...]'' is  a wildcard  exclusion range,  the ``^'' in
  6206.             this case  is treated as a literal character so you won't
  6207.             have to type two of them in a row.
  6208.  
  6209.                Escape characters  work even  inside single  or double
  6210.             quotes.
  6211.  
  6212.                  263 D% echo now ^
  6213.                  is the time
  6214.                  now is the time
  6215.                  264 D% echo "now ^
  6216.                  is the time"
  6217.                  now
  6218.                  is the time
  6219.                  265 D% _
  6220.  
  6221.  
  6222.  
  6223.             Quoting just part of a Word
  6224.  
  6225.                It's possible to combine the quoting mechanisms or use
  6226.             them on  just the  part of a string you want quoted.  For
  6227.             example,
  6228.  
  6229.                  265 D% echo '$cwd='$cwd
  6230.                  $cwd=d:\doug
  6231.  
  6232.                Here's another  example, searching through a series of
  6233.             .csh files,  looking  for  those  that  are  self-loading
  6234.             procedures.  For example, we can spot that whereis.csh is
  6235.             self-loading because it contains a line like this:
  6236.  
  6237.                  whereis $argv
  6238.  
  6239.             To look  for occurrences  of this  sort,  we  might  loop
  6240.             through a  list of  .csh files,  grep'ing  each  for  the
  6241.             filename  (minus   the  directory   and  .csh  extension)
  6242.             followed by white space followed by ``$argv'':
  6243.  
  6244.  
  6245.  
  6246.  
  6247.  
  6248.                                      Page 94
  6249.  
  6250.                                                                       Quoting
  6251.  
  6252.  
  6253.                  266 D% foreach i (~\samples\*.csh)
  6254.                  267 D?    grep $i:b'[ ^t]*$argv' $i
  6255.                  268 D? end
  6256.                  bits $argv
  6257.                  bumpdate $argv
  6258.                  caldate $argv
  6259.                  calendar $argv
  6260.                  :
  6261.  
  6262.             Notice how  the ``$i:b''  part is  outside the  quotes so
  6263.             that the  filename can  be substituted  in and  edited to
  6264.             strip off  the directory  and extension.  Conversely, the
  6265.             ``[ ^t]*'' and  ``$argv'' portions  are inside the quotes
  6266.             to avoid  having them  confused as a wildcard or variable
  6267.             substitution, respectively.
  6268.  
  6269.  
  6270.  
  6271.             Wildcarding with Special Characters
  6272.  
  6273.                If you'd  like to wildcard filenames that have literal
  6274.             $'s, ['s,  quotes or spaces (under HPFS) or other special
  6275.             characters, you'll  have to  quote or  escape the special
  6276.             characters to  turn off  their  special  meanings.    For
  6277.             example,
  6278.  
  6279.                  269 D% ls g:\tmp
  6280.                  $abc          [hello          this name has spaces
  6281.                  270 D% ls '$'*
  6282.                  $abc
  6283.                  271 D% ls *^ *
  6284.                  this name has spaces
  6285.  
  6286.  
  6287.  
  6288.  
  6289.  
  6290.  
  6291.  
  6292.  
  6293.  
  6294.  
  6295.  
  6296.  
  6297.  
  6298.  
  6299.  
  6300.  
  6301.  
  6302.  
  6303.  
  6304.  
  6305.  
  6306.  
  6307.  
  6308.  
  6309.  
  6310.                                      Page 95
  6311.  
  6312.      Expressions
  6313.  
  6314.  
  6315.             
  6316.  
  6317.  
  6318.                                    Expressions
  6319.  
  6320.  
  6321.                As we've  seen, sometimes a character like ``*'' means
  6322.             wildcard and sometimes it means multiply.  The meaning of
  6323.             what you  type is  determined by  the context.  The shell
  6324.             makes a distinction between words, used as arguments to a
  6325.             command versus an expression context.
  6326.  
  6327.                In general,  expressions  are  expected  wherever  the
  6328.             context would  seem to  suggest that  it  would  be  more
  6329.             natural to  think of  calculating a  value as  opposed to
  6330.             using wildcarding to produce a list of filenames.
  6331.  
  6332.  
  6333.  
  6334.             Expressions
  6335.  
  6336.                The shell's expression grammar is based on that of the
  6337.             C language  and provides  the full  range of  arithmetic,
  6338.             logical,   bit,   indexing   and   relation-testing   and
  6339.             assignment operators.  In addition, there are file system
  6340.             tests and  pattern matching  string compares.  To use the
  6341.             shell as simple calculator, use the calc statement.  This
  6342.             example shows  a call  to the square root routine, one of
  6343.             the built-in procedures.
  6344.  
  6345.                  272 D% calc sqrt(2*pi)
  6346.                  2.506628
  6347.  
  6348.             which writes its result to stdout.  If you want to do the
  6349.             calculation silently, use the ``@'' variant:+
  6350.  
  6351.                  273 D% @ r = 12
  6352.                  274 D% @ area = pi * r**2
  6353.                  275 D% calc area
  6354.                  452.389345
  6355.  
  6356.                In addition  to  the  calc  and  @  statements,  other
  6357.             examples  where  an  expression  is  expected  include  a
  6358.             variable index  inside ``[...]'' brackets, in a procedure
  6359.             argument  list  and,  as  we'll  see,  a  number  of  the
  6360.             structured  programming   constructs  such   as  the  for
  6361.             statement.
  6362.  
  6363.  
  6364.  
  6365.             Expression Parsing
  6366.  
  6367.             ____________________
  6368.             + The choice of @ is a pun:  ``at-sign-ment'' statement.
  6369.  
  6370.  
  6371.  
  6372.                                      Page 96
  6373.  
  6374.                                                                   Expressions
  6375.  
  6376.  
  6377.                All commands are first broken down into words.  A word
  6378.             is anything  separated by  a space or a tab or one of the
  6379.             following special  strings: &  ,|, ;, >, <, (, ), &&, ||,
  6380.             >> or <<.
  6381.  
  6382.                After a  command line  has already been broken up into
  6383.             words, if  the context  is an  expression,  it's  further
  6384.             broken up  into  tokens.    A  token  is  a  variable  or
  6385.             procedure name, a character or numeric literal, or one of
  6386.             the expression  operators.   Spacing  between  tokens  is
  6387.             more-or-less arbitrary:   for  example, there's certainly
  6388.             no need  to put  spaces around  an arithmetic operator to
  6389.             separate it from a variable name beside it.
  6390.  
  6391.                Tokens are  separated by  any of  these characters  or
  6392.             character pairs:  &, |, ^, +, -, *, /, %, //, =, !, ~, <,
  6393.             >, (,  ), [,  ], ,, :, ;, -A, -D, -H, -S, -d, -e, -f, -o,
  6394.             -w, -x,  -z, ++,  --, **, <<, >>, ==, !=, =~, !~, +=, -=,
  6395.             *=, /=,  %=, //=,  ^= and **=.  The <=, >=, <<=, >>=, &=,
  6396.             and |=  are always  broken up  into separate words before
  6397.             expression parsing  begins; for  consistency, the  parser
  6398.             will accept  any of  ``op='' assignment  operators with a
  6399.             space between the ``op'' and ``='' parts.+
  6400.  
  6401.                Since the  shell knows that any names it encounters in
  6402.             an expression  must refer to variables or procedures it's
  6403.             not necessary  to  use  a  dollar  sign  to  introduce  a
  6404.             variable name.   In fact, you'll find that performance is
  6405.             actually a  bit better  if you  do not use a dollar sign.
  6406.             The reason  is because a $-style variable substitution is
  6407.             evaluated  by   converting  the  internal  value  of  the
  6408.             variable to a string and pasting that into the expression
  6409.             where quite  often the  next step  is just  to convert it
  6410.             right back again into the integer or floating point value
  6411.             it started  out as.  Also, if floating point is involved,
  6412.             you may  notice some  loss  of  precision.    (But  don't
  6413.             misunderstand, it is still perfectly legal to use $-style
  6414.             variable and other substitutions in an expression.)
  6415.  
  6416.                Character literals must appear inside single or double
  6417.             quotes.   Numeric literals  can be  entered  in  decimal,
  6418.             octal or  hex.  Octal numbers can contain only the digits
  6419.             0 through  7 and  must begin  with 0.   Hex  numbers must
  6420.             start with  ``0x'' and contain only 0 through f.  (Either
  6421.             upper or lower case is acceptable.)
  6422.  
  6423.  
  6424.  
  6425.             Expression Operators
  6426.             ____________________
  6427.             + The grammar is not perfectly lr(1):  proper recognition
  6428.               of the  file system  tests and  the assignment operator
  6429.               requires that  parsing decisions in some places have to
  6430.               look ahead two tokens, not just one.
  6431.  
  6432.  
  6433.  
  6434.                                      Page 97
  6435.  
  6436.      Expressions
  6437.  
  6438.  
  6439.                Expressions are  evaluated according  to the  relative
  6440.             precedence of  each operator  in  the  expression.    For
  6441.             example, multiplication  is done  before addition.    The
  6442.             complete precedence hierarchy is shown in tabular form in
  6443.             the language reference.
  6444.  
  6445.                  276 D% calc 2 + 3*5
  6446.                  17
  6447.  
  6448.                Some of  the operators  will  be  foreign,  though  we
  6449.             trust, not  too difficult  to use.  The file system tests
  6450.             are unary  operators.   Each takes  the name of a file or
  6451.             directory and tests it for existence, zero-length or some
  6452.             other interesting characteristic.  Since the operand is a
  6453.             pathname, the  parser temporarily  shifts to word mode to
  6454.             read it  because word mode is more natural for pathnames.
  6455.             The pathname  can include  wildcards and  should  not  be
  6456.             enclosed in  quotes.  In the example that follows, ``-e''
  6457.             tests for  existence; ``-D''  tests whether the name is a
  6458.             directory.
  6459.  
  6460.                  277 D% cd ~\samples
  6461.                  278 D% ls
  6462.                  args.c        colors.csh    factor.csh    mcvisa.csh
  6463.                  readme
  6464.                  args.exe      deltaday.csh  finance.csh   myecho.c
  6465.                  ts.csh
  6466.                  bits.csh      dumpenv.c     getprio.c     myecho.exe
  6467.                  viopaste.c
  6468.                  bumpdate.csh  dumpenv.exe   getprio.exe   newfiles.csh
  6469.                  viopaste.exe
  6470.                  caldate.csh   duplicat.csh  julian.csh    rcode.c
  6471.                  weekday.csh
  6472.                  calendar.csh  easter.csh    makecpgm.csh  rcode.exe
  6473.                  279 D% echo a*c
  6474.                  args.c
  6475.                  280 D% calc -e a*c
  6476.                  1
  6477.                  281 D% calc -D !$
  6478.                  calc -D a*c
  6479.                  0
  6480.  
  6481.  
  6482.  
  6483.             File System Tests
  6484.  
  6485.                The value returned from a file system test is always 1
  6486.             or 0; there are no restrictions on how the value might be
  6487.             used in further calculations.
  6488.  
  6489.                  282 D% calc 1 + (!*) + (-e myecho.c)
  6490.                  calc 1 + ( -D a*c ) + ( -e myecho.c )
  6491.                  2
  6492.  
  6493.  
  6494.  
  6495.  
  6496.                                      Page 98
  6497.  
  6498.                                                                   Expressions
  6499.  
  6500.  
  6501.             Increment and Decrement Operators
  6502.  
  6503.                The unary  incrementing and decrementing operators are
  6504.             ``++'' and  ``--''. Pasting  one in  front of  a variable
  6505.             name bumps the variable, then returns the value.  Pasting
  6506.             one after  the name  bumps the  variable but  returns the
  6507.             prior state.
  6508.  
  6509.                  283 D% calc x = 1
  6510.                  1
  6511.                  284 D% calc ++x
  6512.                  2
  6513.                  285 D% calc x++
  6514.                  2
  6515.                  286 D% calc x
  6516.                  3
  6517.                  287 D% calc --x
  6518.                  2
  6519.  
  6520.  
  6521.  
  6522.             Bit Shifting
  6523.  
  6524.                The ``<<''  and ``>>'' bit shifting operators shift an
  6525.             integer value  on the left by the number of bit positions
  6526.             given by  the integer  value on  the right.  Bits shifted
  6527.             off the end are lost; values shifted in are always 0.
  6528.  
  6529.                  288 D% calc x << 3
  6530.                  8
  6531.                  289 D% calc x >> 10
  6532.                  0
  6533.  
  6534.  
  6535.  
  6536.             Bit Not Operation
  6537.  
  6538.                The unary  ``~'' operator  returns the bit-wise not of
  6539.             an integer  operand.  As this example shows, integers are
  6540.             32-bit signed values.
  6541.  
  6542.                  290 D% calc ~5
  6543.                  -6
  6544.                  291 D% calc 0xfffffffa
  6545.                  -6
  6546.                  292 D% calc ~!$
  6547.                  calc ~0xfffffffa
  6548.                  5
  6549.  
  6550.  
  6551.  
  6552.             Logical Not
  6553.  
  6554.  
  6555.  
  6556.  
  6557.  
  6558.                                      Page 99
  6559.  
  6560.      Expressions
  6561.  
  6562.  
  6563.                The unary  ``!'' operator returns the logical not.  If
  6564.             the operand  is non-zero,  0 is returned, otherwise 1. In
  6565.             this  example,   the  parentheses   or  space  after  the
  6566.             exclamation are deliberate to avoid having the expression
  6567.             confused as a history reference.
  6568.  
  6569.                  293 D% calc !(5.1)
  6570.                  0
  6571.                  294 D% calc ! 0
  6572.                  1
  6573.  
  6574.  
  6575.  
  6576.             Exponentiation
  6577.  
  6578.                The ``**''  operator is  for exponentiation.  The left
  6579.             operand is raised to power of the right operand.
  6580.  
  6581.                  295 D% calc 2 ** 500
  6582.                  3.27339061e+150
  6583.  
  6584.  
  6585.  
  6586.             Modulo and Integer Division
  6587.  
  6588.                The ``%''  operator is for modulo division and returns
  6589.             the remainder.
  6590.  
  6591.                  296 D% calc 22 % 7
  6592.                  1
  6593.  
  6594.                A  related  ``//''  operator  does  integer  division.
  6595.             Where the standard ``/'' operator might return a floating
  6596.             point result,  ``//'' gives  just the integer part of any
  6597.             division.
  6598.  
  6599.                  297 D% calc 8/3
  6600.                  2.666667
  6601.                  298 D% calc 8//3
  6602.                  2
  6603.  
  6604.  
  6605.  
  6606.             Comparison Operators
  6607.  
  6608.                The ``==''  operator tests  for equality;  the  single
  6609.             ``='' means  assignment.    The  ``!='',  ``<'',  ``<='',
  6610.             ``>='', and  ``>''  operators  are  all  straight-forward
  6611.             tests of  ``not equal,''  ``less than,''  ``less than  or
  6612.             equal,'' etc.   Comparisons  of strings are as easy as of
  6613.             numbers.
  6614.  
  6615.                  299 D% calc x = 3
  6616.                  3
  6617.  
  6618.  
  6619.  
  6620.                                      Page 100
  6621.  
  6622.                                                                   Expressions
  6623.  
  6624.  
  6625.                  300 D% calc x == 5
  6626.                  0
  6627.                  301 D% calc "able" < "baker"
  6628.                  1
  6629.  
  6630.                When the shell is asked to compare two expressions, it
  6631.             first tries to coerce them to numeric values.  This is so
  6632.             that, e.g.,  a string  containing ``16'' compares greater
  6633.             than ``2'' even though a simple string compare would give
  6634.             the opposite result.
  6635.  
  6636.  
  6637.  
  6638.             Pattern Matching Operators
  6639.  
  6640.                The ``=~''and  ``!~'' are  the ``pattern matches'' and
  6641.             ``pattern fails''  tests.   These are done in pretty much
  6642.             the same  way wildcarding  is done.   On  the right  is a
  6643.             pattern string  possibly containing  wildcard characters.
  6644.             It's compared against the string on the left the same way
  6645.             a wildcard  expansion would  be done  except  that  here,
  6646.             comparisons  are  case-sensitive  and  where  alternation
  6647.             appears, the  match succeeds  if any  of  the  alternates
  6648.             matches.
  6649.  
  6650.                  302 D% calc "Now is" =~ "N*i*"
  6651.                  1
  6652.                  303 D% calc "Now is" !~ "Now is"
  6653.                  0
  6654.                  304 D% calc "Now is" =~ "n*i*"
  6655.                  0
  6656.                  305 D% calc "Now is" =~ "{n,No}*i{s,the}"
  6657.                  1
  6658.  
  6659.  
  6660.  
  6661.             Bitwise And, Xor and Or Operators
  6662.  
  6663.                The ``&'',  ``^'' and ``|'' operators perform bit-wise
  6664.             and, xor and or operations on integer operands.
  6665.  
  6666.                  306 D% calc 5 & 4
  6667.                  4
  6668.                  307 D% calc 5 ^ 3
  6669.                  6
  6670.                  308 D% calc 5 | 3
  6671.                  7
  6672.  
  6673.  
  6674.  
  6675.             Logical And and Or
  6676.  
  6677.                The ``&&''  and ``||''  operators perform  logical and
  6678.             and or operations:
  6679.  
  6680.  
  6681.  
  6682.                                      Page 101
  6683.  
  6684.      Expressions
  6685.  
  6686.  
  6687.                  309 D% calc 5 && 4
  6688.                  1
  6689.                  310 D% calc 0 && 4
  6690.                  0
  6691.                  311 D% calc 5 || 3
  6692.                  1
  6693.                  312 D% calc 5 || 0
  6694.                  1
  6695.  
  6696.  
  6697.  
  6698.             The ?: Operator
  6699.  
  6700.                The  ``?:''   trinary  operator  selects  between  two
  6701.             alternate expressions based on the logical (i.e., true or
  6702.             false) value of the first operand.
  6703.  
  6704.                  313 D% calc 0 ? "hello" : "goodby"
  6705.                  goodby
  6706.                  314 D% calc (5 > 3) ? "hit" : "miss"
  6707.                  hit
  6708.  
  6709.  
  6710.  
  6711.             The {...} Operator
  6712.  
  6713.                The ``{...}''  grouping operator  allows you  to run a
  6714.             command and  evaluate its result as a 1 if it succeeds or
  6715.             a zero if it fails.  For example:
  6716.  
  6717.                  315 D% calc {echo hello}
  6718.                  hello
  6719.                  1
  6720.                  316 D% calc {cd \nonexistent}
  6721.                  csh:  Couldn't change the current directory to
  6722.                  '\nonexistent'.
  6723.                  0
  6724.  
  6725.  
  6726.  
  6727.             The Op= Operators
  6728.  
  6729.                Finally, the various ``op='' operators apply the op to
  6730.             the left  and right  operands, then  assign the result to
  6731.             the left operand.
  6732.  
  6733.                  317 D% calc x = 2
  6734.                  2
  6735.                  318 D% calc x **= 500
  6736.                  3.27339061e+150
  6737.                  319 D% calc x
  6738.                  3.27339061e+150
  6739.  
  6740.  
  6741.  
  6742.  
  6743.  
  6744.                                      Page 102
  6745.  
  6746.                                                                   Expressions
  6747.  
  6748.  
  6749.             Type Conversions
  6750.  
  6751.                The  shell   always  tries   to  evaluate  expressions
  6752.             ``sensibly'' by  doing any  type conversions  that  might
  6753.             seem necessary.   If an integer calculation results in an
  6754.             overflow, the  shell  shifts  automatically  to  floating
  6755.             point.
  6756.  
  6757.                  320 D% calc 2**30
  6758.                  1073741824
  6759.                  321 D% calc 2**200
  6760.                  1.606938e+060
  6761.  
  6762.                If a  character string  was given  but an  integer  is
  6763.             needed, the  shell tries  to  do  that  conversion  also.
  6764.             Because these  conversions happen  automatically, without
  6765.             any fanfare, the following literals all compare equal:
  6766.  
  6767.                  27    27.0    033    0x1B    " 27 "    '   0x1b '
  6768.  
  6769.             (Null strings  and strings consisting only of white space
  6770.             are considered  equal to  zero.    This  is  particularly
  6771.             convenient for  local variables,  which are initially set
  6772.             to null strings.)
  6773.  
  6774.                The shell  does automatic  conversions to  a character
  6775.             string format  when the result is being printed.  Numeric
  6776.             results are  always shown in decimal.  In this example, a
  6777.             procedure, the  built-in square  root routine, is invoked
  6778.             as a  command; the  value it  returns is  converted  from
  6779.             floating point to character string and printed.
  6780.  
  6781.                  322 D% sqrt 2
  6782.                  1.414213
  6783.  
  6784.                 The  shell also  converts to  a character string when
  6785.             you reference an array but use it as if it were not.
  6786.  
  6787.                  323 D% set x = Now is the time
  6788.                  324 D% cd ~\samples; myecho $x
  6789.                  'myecho' 'Now' 'is' 'the' 'time'
  6790.                  arg length = 23 characters
  6791.                  325 D% @ y = x
  6792.                  326 D% myecho $y
  6793.                  'myecho' 'Now is the time'
  6794.                  arg length = 23 characters
  6795.  
  6796.  
  6797.  
  6798.  
  6799.  
  6800.  
  6801.  
  6802.  
  6803.  
  6804.  
  6805.  
  6806.                                      Page 103
  6807.  
  6808.      Expressions
  6809.  
  6810.  
  6811.             
  6812.  
  6813.  
  6814.  
  6815.  
  6816.  
  6817.  
  6818.  
  6819.  
  6820.  
  6821.  
  6822.  
  6823.  
  6824.  
  6825.  
  6826.  
  6827.  
  6828.  
  6829.  
  6830.  
  6831.  
  6832.  
  6833.  
  6834.  
  6835.  
  6836.  
  6837.  
  6838.  
  6839.  
  6840.  
  6841.  
  6842.  
  6843.  
  6844.  
  6845.  
  6846.  
  6847.  
  6848.  
  6849.  
  6850.  
  6851.  
  6852.  
  6853.  
  6854.  
  6855.  
  6856.  
  6857.  
  6858.  
  6859.  
  6860.  
  6861.  
  6862.  
  6863.  
  6864.  
  6865.  
  6866.  
  6867.  
  6868.                                      Page 104
  6869.  
  6870.                                                                       Aliases
  6871.  
  6872.  
  6873.             
  6874.  
  6875.  
  6876.                                      Aliases
  6877.  
  6878.  
  6879.                Aliases are  a quick shorthand technique.  If you type
  6880.             an alias  at the beginning of a command, it's replaced by
  6881.             whatever the alias is defined as.  They're intended to be
  6882.             used  for   relatively  simple  abbreviations:    if  any
  6883.             arguments are  needed, you  have to  be able to type them
  6884.             onto the end.  (More complex situations will have to wait
  6885.             until we cover procedures.)
  6886.  
  6887.                To list  the aliases  currently defined, use the alias
  6888.             command:
  6889.  
  6890.                  327 D% alias
  6891.                  cdd          cd +c
  6892.                  copy         local s ; @ s = nowild ; @ nowild = 1 ;
  6893.                  safecopy
  6894.                  date         dt
  6895.                  del          local s ; @ s = nowild ; @ nowild = 1 ;
  6896.                  safedel
  6897.                  dir          cmd /c dir
  6898.                  erase        del
  6899.                  h            history
  6900.                  help         helpmsg
  6901.                  label        cmd /c label
  6902.                  ll           ls -L
  6903.                  md           mkdir
  6904.                  mi           more -i
  6905.                  rd           rmdir
  6906.                  ren          rename
  6907.                  rename       local s ; @ s = nowild ; @ nowild = 1 ;
  6908.                  saferename
  6909.                  ro           rotd
  6910.                  start        cmd /c start
  6911.                  type         cat
  6912.                  vol          vl
  6913.                  xcopy        local s ; @ s = nowild ; @ nowild = 1 ;
  6914.                  safexcopy
  6915.  
  6916.                Some aliases  are  used  to  intercept  references  to
  6917.             cmd.exe's built-in  commands.   For example,  this is how
  6918.             dir is run.  Other aliases give simple alternate names to
  6919.             a command, e.g., rename for mv.  Still others are used to
  6920.             customize a  command with  a useful option.  For example,
  6921.             mi runs  more but  starts it  immediately in  interactive
  6922.             mode, which  means the  screen is  cleared first; in a PM
  6923.             text window, this tends to run faster.
  6924.  
  6925.  
  6926.  
  6927.  
  6928.  
  6929.  
  6930.                                      Page 105
  6931.  
  6932.      Aliases
  6933.  
  6934.  
  6935.                To find  out how  any particular alias is defined, use
  6936.             the alias command with only the name you're interested in
  6937.             as an operand.
  6938.  
  6939.                  328 D% alias mi
  6940.                  mi           more -i
  6941.  
  6942.                To create a new alias, type the alias command followed
  6943.             by the  name of  alias being  created and  word  list  it
  6944.             should be expanded into:
  6945.  
  6946.                  329 D% alias hello echo hello world
  6947.                  330 D% hello
  6948.                  hello world
  6949.  
  6950.                If you  define an  alias that refers to itself, either
  6951.             directly or  via  other  aliases,  the  shell  traps  the
  6952.             reference rather  than  allowing  it  to  expand  without
  6953.             limit:
  6954.  
  6955.                  331 D% alias hello (echo infinite; hello again)
  6956.                  332 D% hello
  6957.                  csh:  A loop in the alias definitions was
  6958.                  encountered and trapped.
  6959.  
  6960.                This raises  the question  how  you  might  define  an
  6961.             alias, say,  ls, that  intercepts references  to  the  ls
  6962.             utility without  getting into a loop.  The answer is that
  6963.             the shell  considers it  a special case if the first word
  6964.             in the  expansion of  the alias  is the same as its name.
  6965.             Here's an  alias that  causes ls  to always  display  all
  6966.             files:
  6967.  
  6968.                  333 D% alias ls ls +a
  6969.  
  6970.  
  6971.  
  6972.             Implementation Details
  6973.  
  6974.                The alias  mechanism is  actually part  of the parsing
  6975.             mechanism rather  than a run-time feature of the C shell.
  6976.             What that  means is that the alias expansion is done when
  6977.             the statement  is first  read, not  when  it's  executed.
  6978.             Here's  an   example  where  we  attempt  to  change  the
  6979.             definition of  an alias  inside a  loop.   Notice that it
  6980.             doesn't have  any effect  until we exit the loop.  That's
  6981.             because the  whole loop  is being  compiled  as  a  block
  6982.             before any part of it is executed.
  6983.  
  6984.                  334 D% alias foo echo this is life
  6985.                  335 D% foreach i (hello world)
  6986.                  336 D?    alias foo echo $i
  6987.                  337 D?    foo
  6988.                  338 D? end
  6989.  
  6990.  
  6991.  
  6992.                                      Page 106
  6993.  
  6994.                                                                       Aliases
  6995.  
  6996.  
  6997.                  this is life
  6998.                  this is life
  6999.                  339 D% foo
  7000.                  world
  7001.  
  7002.  
  7003.  
  7004.  
  7005.  
  7006.  
  7007.  
  7008.  
  7009.  
  7010.  
  7011.  
  7012.  
  7013.  
  7014.  
  7015.  
  7016.  
  7017.  
  7018.  
  7019.  
  7020.  
  7021.  
  7022.  
  7023.  
  7024.  
  7025.  
  7026.  
  7027.  
  7028.  
  7029.  
  7030.  
  7031.  
  7032.  
  7033.  
  7034.  
  7035.  
  7036.  
  7037.  
  7038.  
  7039.  
  7040.  
  7041.  
  7042.  
  7043.  
  7044.  
  7045.  
  7046.  
  7047.  
  7048.  
  7049.  
  7050.  
  7051.  
  7052.  
  7053.  
  7054.                                      Page 107
  7055.  
  7056.      Programming Constructs
  7057.  
  7058.  
  7059.             
  7060.  
  7061.  
  7062.                              Programming Constructs
  7063.  
  7064.  
  7065.                This chapter  outlines the various structures provided
  7066.             for connecting  statements together:   describing  serial
  7067.             relationships, conditional  execution, iteration  and how
  7068.             procedures are defined and used.
  7069.  
  7070.  
  7071.  
  7072.             Serial Execution
  7073.  
  7074.                As we've  seen already,  commands typed  on successive
  7075.             lines  are   executed  serially,  one  after  the  other.
  7076.             Writing several  commands on  one  line  with  semicolons
  7077.             between them does the same thing.
  7078.  
  7079.                  340 D% echo hello; echo world
  7080.                  hello
  7081.                  world
  7082.                  341 D% _
  7083.  
  7084.                Notice that  in contrast to cmd.exe, the shell doesn't
  7085.             pass the semicolon to the application you invoke.  If you
  7086.             really do  want to  pass a semicolon, e.g., to the linker
  7087.             to indicate  the end of the arguments, you have to escape
  7088.             it or put it inside quotes.
  7089.  
  7090.                 A  non-zero return code is not normally considered an
  7091.             error:  regardless of the return code from any particular
  7092.             command, serial  execution continues.  We can demonstrate
  7093.             this with  the rcode  utility in  the  samples  directory
  7094.             which prints,  then exits  with the return code value you
  7095.             pass it on the command line.  This example also shows how
  7096.             you can  retrieve the  return  code  of  the  last  child
  7097.             process by referring to the built-in status variable.
  7098.  
  7099.                  341 D% cd ~\samples
  7100.                  342 D% rcode 1; rcode 2
  7101.                  1
  7102.                  2
  7103.                  343 D% calc status
  7104.                  2
  7105.  
  7106.                It's also  possible to  describe a  conditional serial
  7107.             relationship.   If statements  are joined  by ``&&'', the
  7108.             second one  is executed  only if the return code from the
  7109.             first one  is 0,  i.e., if  the first statement succeeds.
  7110.             If  statements  are  joined  by  ``||'',  the  second  is
  7111.             executed only  if the  first one  fails, i.e.,  returns a
  7112.             non-zero return code.
  7113.  
  7114.  
  7115.  
  7116.                                      Page 108
  7117.  
  7118.                                                        Programming Constructs
  7119.  
  7120.  
  7121.                  344 D% rcode 0 || rcode 1
  7122.                  0
  7123.                  345 D% rcode 1 || rcode 2
  7124.                  1
  7125.                  2
  7126.                  346 D% rcode 0 && rcode 1
  7127.                  0
  7128.                  1
  7129.                  347 D% rcode 1 && rcode 2
  7130.                  1
  7131.  
  7132.  
  7133.  
  7134.             Statements and Statement Lists
  7135.  
  7136.                I/O   redirectors   and   statement   connectors   are
  7137.             recognized  according  to  a  precedence.    Just  as  in
  7138.             expressions, where ``*'' is done before ``+'', statements
  7139.             are parsed  so that  some things  are done before others.
  7140.             I/O redirection  comes before  piping which  comes before
  7141.             conditional execution which comes before serializing with
  7142.             semicolons.  For example:
  7143.  
  7144.                  348 D% echo hello; echo world | wc
  7145.                  hello
  7146.                          1        1        7
  7147.  
  7148.                The  shell   makes  a   special  distinction   between
  7149.             individual statements,  no matter  how complex, and lists
  7150.             of statements  typed on  separate lines  or separated  by
  7151.             semicolons.
  7152.  
  7153.                Here's an example using the time command, which runs a
  7154.             statement and  prints out  the hours, minutes and seconds
  7155.             it took.   time  expects a single statement as a operand;
  7156.             if you  type a semicolon, the time command (together with
  7157.             its operand) becomes just one statement in the list.
  7158.  
  7159.                  349 D% time echo hello world | wc
  7160.                          1        2       13
  7161.                  0:00:00.50
  7162.                  350 D% time echo hello; echo world
  7163.                  hello
  7164.                  0:00:00.00
  7165.                  world
  7166.  
  7167.  
  7168.  
  7169.             Parenthesis
  7170.  
  7171.                There are  two ways  to group  a  list  of  statements
  7172.             together to  make them  act like a single statement.  The
  7173.             simplest way is with parenthesis, which work the way they
  7174.  
  7175.  
  7176.  
  7177.  
  7178.                                      Page 109
  7179.  
  7180.      Programming Constructs
  7181.  
  7182.  
  7183.             would in  an expression:  even if the operator inside the
  7184.             parentheses are of lower precedence, they're done first.
  7185.  
  7186.                  351 D% (echo hello; echo world) | wc
  7187.                          2        2       14
  7188.                  352 D% time (echo hello; echo world)
  7189.                  hello
  7190.                  world
  7191.                  0:00:00.00
  7192.  
  7193.                A parenthesized group gets its own copy of the current
  7194.             directory and  disk.   This makes it convenient to change
  7195.             directories inside  the group and go do something without
  7196.             having to change back afterward.
  7197.  
  7198.                  353 D% cd
  7199.                  d:\doug\samples
  7200.                  354 D% (cd ..; cd)
  7201.                  d:\doug
  7202.                  355 D% cd
  7203.                  d:\doug\samples
  7204.  
  7205.                The actual  implementation uses  the  directory  stack
  7206.             mechanism:   at entry to the group, the current directory
  7207.             is pushed  onto the  directory stack and at exit, the top
  7208.             entry is popped.
  7209.  
  7210.                  356 D% dirs
  7211.                  d:\doug\samples
  7212.                  357 D% ( dirs )
  7213.                  d:\doug\samples
  7214.                  d:\doug\samples
  7215.                  358 D% dirs
  7216.                  d:\doug\samples
  7217.  
  7218.  
  7219.  
  7220.             Control Structures
  7221.  
  7222.                The more general way of connecting statements together
  7223.             is  with   control  structures,  which  provide  ways  of
  7224.             describing conditional  or iterative  execution  or  even
  7225.             (with procedures)  adding new vocabulary to the language.
  7226.             You can  use a  control structure anywhere a statement is
  7227.             allowed.
  7228.  
  7229.                The  language   is  completely   recursive:    control
  7230.             structures can  be nested inside control structures, etc.
  7231.             A statement  can  be  arbitrarily  complex.    Here's  an
  7232.             example timing  a statement  that turns  out to  be a for
  7233.             loop piped to a wc and inside the for loop ...
  7234.  
  7235.                  359 D% time for i = 1 to 3 do
  7236.                  360 D?         time echo hello world | wc
  7237.  
  7238.  
  7239.  
  7240.                                      Page 110
  7241.  
  7242.                                                        Programming Constructs
  7243.  
  7244.  
  7245.                  361 D?      end | wc
  7246.                          6       12      126
  7247.                  0:00:01.03
  7248.  
  7249.  
  7250.  
  7251.             If Statement
  7252.  
  7253.                The if  statement comes  in two forms.  The short form
  7254.             is convenient if the choice is only between executing and
  7255.             not executing  a single  statement, which  appears on the
  7256.             same line.
  7257.  
  7258.                  362 D% if (5 == 2 + 3) echo yes
  7259.                  yes
  7260.                  363 D% if (5 == 10) echo really
  7261.                  364 D% _
  7262.  
  7263.                The longer form provides the more traditional if-then-
  7264.             else structure.   Indentation is a matter of choice, it's
  7265.             used in these examples merely to improve readability.
  7266.  
  7267.                  364 D% if (5 == 10) then
  7268.                  365 D?    echo 5 == 10
  7269.                  366 D? else
  7270.                  367 D?    echo 5 is not 10
  7271.                  368 D? end
  7272.                  5 is not 10
  7273.                  369 D% _
  7274.  
  7275.  
  7276.  
  7277.             Switch Statement
  7278.  
  7279.                The switch  statement works  by attempting  to pattern
  7280.             match the  switch value  against a  series of alternative
  7281.             cases.   The switch  and case values can all be arbitrary
  7282.             expressions.   If any  pattern match  succeeds, execution
  7283.             begins with  the next  statement following and continues,
  7284.             skipping over  any interspersed case clauses until either
  7285.             the end  of the  switch block  or a  break  statement  is
  7286.             reached.
  7287.  
  7288.                  369 D% switch ("hello world")
  7289.                  370 D?    case 5:
  7290.                  371 D?       echo hit 5
  7291.                  372 D?    case "h*":
  7292.                  373 D?       echo hit "h*"
  7293.                  374 D?    case "x*":
  7294.                  375 D?       echo hit "x*"
  7295.                  376 D?       break
  7296.                  377 D?    case 43.2:
  7297.                  378 D?       echo hit 43.2
  7298.                  379 D?    default:
  7299.  
  7300.  
  7301.  
  7302.                                      Page 111
  7303.  
  7304.      Programming Constructs
  7305.  
  7306.  
  7307.                  380 D?       echo did not hit
  7308.                  381 D? end
  7309.                  hit h*
  7310.                  hit x*
  7311.  
  7312.                The break  statement used  here  causes  execution  to
  7313.             ``break out  of'' the  innermost control  structure.   If
  7314.             you're nested several layers deep into control structures
  7315.             and want to break out of a higher level structure you can
  7316.             label the higher level structure and specify that name on
  7317.             the break statement.
  7318.  
  7319.  
  7320.  
  7321.  
  7322.  
  7323.  
  7324.  
  7325.  
  7326.  
  7327.  
  7328.  
  7329.  
  7330.  
  7331.  
  7332.  
  7333.  
  7334.  
  7335.  
  7336.  
  7337.  
  7338.  
  7339.  
  7340.  
  7341.  
  7342.  
  7343.  
  7344.  
  7345.  
  7346.  
  7347.  
  7348.  
  7349.  
  7350.  
  7351.  
  7352.  
  7353.  
  7354.  
  7355.  
  7356.  
  7357.  
  7358.  
  7359.  
  7360.  
  7361.  
  7362.  
  7363.  
  7364.                                      Page 112
  7365.  
  7366.                                                        Programming Constructs
  7367.  
  7368.  
  7369.             Foreach Statement
  7370.  
  7371.                The foreach statement is designed for iterating over a
  7372.             series of words.  In this example, i is iterated over the
  7373.             list of  all the  files in  the samples  directory.  Each
  7374.             one, in  turn, is tested to see if it's executable (i.e.,
  7375.             has a .csh, .cmd, .exe or .com extension.)
  7376.  
  7377.                  382 D% cd ~\samples
  7378.                  383 D% ls
  7379.                  args.c       dumpenv.c    finance.csh  myecho.exe
  7380.                  readme
  7381.                  args.exe     dumpenv.exe  makecpgm.csh rcode.c
  7382.                  bits.csh     factor.csh   myecho.c     rcode.exe
  7383.                  384 D% foreach i (*)
  7384.                  385 D?    if (-x $i) echo $i is executable
  7385.                  386 D? end
  7386.                  args.exe is executable
  7387.                  bits.csh is executable
  7388.                  dumpenv.exe is executable
  7389.                  factor.csh is executable
  7390.                  finance.csh is executable
  7391.                  makecpgm.csh is executable
  7392.                  myecho.exe is executable
  7393.                  rcode.exe is executable
  7394.  
  7395.  
  7396.  
  7397.             For Statement
  7398.  
  7399.                The for  statement provides more traditional iteration
  7400.             over numerical values.  If you specify a range (e.g., ``1
  7401.             to 3'')  but don't  specify the  increment, 1 is assumed.
  7402.             Although  this   example  shows  iteration  over  integer
  7403.             values, floating point values are equally acceptable.
  7404.  
  7405.                  387 D% for i = 1 to 3 do
  7406.                  388 D?    echo $i
  7407.                  389 D? end
  7408.                  1
  7409.                  2
  7410.                  3
  7411.  
  7412.                You  can  also  iterate  over  a  list  of  ranges  or
  7413.             individual  values.    The  to  and  by  clauses  may  be
  7414.             specified in either order.
  7415.  
  7416.                  390 D% for i = 1, 4, 7, 12, -4 to 6 by 3 do
  7417.                  391 D?    echo $i
  7418.                  392 D? end
  7419.                  1
  7420.                  4
  7421.                  7
  7422.                  12
  7423.  
  7424.  
  7425.  
  7426.                                      Page 113
  7427.  
  7428.      Programming Constructs
  7429.  
  7430.  
  7431.                  -4
  7432.                  -1
  7433.                  2
  7434.                  5
  7435.  
  7436.  
  7437.  
  7438.             While Statement
  7439.  
  7440.                The while  statement works  in the traditional manner,
  7441.             iterating so  long as  the while condition is true.  This
  7442.             example keeps  popping up  through the  various levels of
  7443.             parent directories  until it  reaches the root.  fullpath
  7444.             is one  of the  built-in procedures; it return the fully-
  7445.             qualified pathname of its argument.  Notice that fullpath
  7446.             is invoked  in three  different ways:  on line 384, as if
  7447.             it were  a command, on 385 in more conventional procedure
  7448.             syntax and  on 386,  where it's  substituted in  as if it
  7449.             were a variable.
  7450.  
  7451.                  393 D% fullpath .
  7452.                  d:\doug\samples
  7453.                  394 D% while (fullpath(".") !~ "[a-zA-Z]:\")
  7454.                  395 D?    echo $fullpath(".")
  7455.                  396 D?    cd ..
  7456.                  397 D? end
  7457.                  d:\doug\samples
  7458.                  d:\doug
  7459.                  398 D% cd
  7460.                  d:\
  7461.  
  7462.  
  7463.  
  7464.             Repeat Statement
  7465.  
  7466.                The repeat  statement has  two forms.   In  the  short
  7467.             form, a  numeric constant  (not an  expression) specifies
  7468.             the number of times to execute the statement following on
  7469.             the same line.
  7470.  
  7471.                  399 D% repeat 4 echo do this again
  7472.                  do this again
  7473.                  do this again
  7474.                  do this again
  7475.                  do this again
  7476.  
  7477.                In  the   long  form,   repeat   provides   the   more
  7478.             conventional repeat  structure, iterating until some exit
  7479.             condition satisfied.
  7480.  
  7481.                  400 D% calc i = 1
  7482.                  1
  7483.                  401 D% repeat
  7484.                  402 D?    calc i++
  7485.  
  7486.  
  7487.  
  7488.                                      Page 114
  7489.  
  7490.                                                        Programming Constructs
  7491.  
  7492.  
  7493.                  403 D? until (i > 5)
  7494.                  1
  7495.                  2
  7496.                  3
  7497.                  4
  7498.                  5
  7499.  
  7500.  
  7501.  
  7502.             Procedures
  7503.  
  7504.                Procedures, as  in  any  high-level  language,  are  a
  7505.             convenient way to package together a series of statements
  7506.             as a  more convenient  operation.   Once you've defined a
  7507.             procedure, you  can invoke  it simply as if it were a new
  7508.             command.
  7509.  
  7510.                  404 D% proc hello()
  7511.                  405 D?    echo hello world
  7512.                  406 D? end
  7513.                  407 D% hello
  7514.                  hello world
  7515.  
  7516.                The proc  statement can  also  be  used  to  ask  what
  7517.             procedures  are  already  defined  or  what  arguments  a
  7518.             particular procedure takes:
  7519.  
  7520.                  408 D% proc hello
  7521.                  hello        ( )
  7522.                  409 D% proc | mi
  7523.                  abs          ( x )
  7524.                  acos         ( x )
  7525.                  asin         ( x )
  7526.                  :
  7527.                  :
  7528.                  samepath     ( a, b )
  7529.                  sin          ( x )
  7530.                  sinh         ( x )
  7531.                  --- more --- (Press H for Help)
  7532.  
  7533.                You can  explicitly discard  a definition with unproc;
  7534.             otherwise the  shell remembers  any procedure you tell it
  7535.             until you exit the shell or give it a new definition.
  7536.  
  7537.                  410 D% unproc hello
  7538.                  411 D% hello
  7539.                  csh:  Couldn't find an executable file named
  7540.                  'hello'.
  7541.  
  7542.                When you  give the  shell a  procedure definition, the
  7543.             shell compiles  it into an internal form so that the next
  7544.             time you  refer to  it, it'll save the reparsing time and
  7545.             run much  faster.   As an  example, unproc   the  whereis
  7546.             procedure to  make the  shell reload  the definition from
  7547.  
  7548.  
  7549.  
  7550.                                      Page 115
  7551.  
  7552.      Programming Constructs
  7553.  
  7554.  
  7555.             the .csh  file and  see what  that does  to the execution
  7556.             time:
  7557.  
  7558.                  412 D% unproc whereis
  7559.                  413 D% time whereis ls
  7560.                  f:\os2\bin\ls.exe
  7561.                  0:00:02.15
  7562.                  414 D% !!
  7563.                  time whereis ls
  7564.                  f:\os2\bin\ls.exe
  7565.                  0:00:01.28
  7566.  
  7567.                The namespace  for procedures  is shared among all the
  7568.             threads:   if one  thread creates  a  new  procedure,  it
  7569.             becomes usable immediately by all the other threads.
  7570.  
  7571.  
  7572.  
  7573.             Arguments
  7574.  
  7575.                You can  write a  procedure so  it expects  arguments,
  7576.             just as  you would  in any  other  high  level  language.
  7577.             Argument names  are somewhat like local variables:  their
  7578.             initial values  are set  at entry  to a procedure, hiding
  7579.             any previous  definition; they  go away  as soon you exit
  7580.             the procedure  code.    Here's  a  simple  example  which
  7581.             compares the timestamps on two files.
  7582.  
  7583.                  415 D% proc comparedates(a, b)
  7584.                  416 D?    if (`newer $a $b`) then
  7585.                  417 D?       echo $a is newer than $b
  7586.                  418 D?    else
  7587.                  419 D?       if (samepath(a, b)) then
  7588.                  420 D?          echo $a and $b are the same file!
  7589.                  421 D?       else
  7590.                  422 D?          echo $a is older than $b
  7591.                  423 D?       end
  7592.                  424 D?    end
  7593.                  425 D? end
  7594.                  426 D% comparedates `whereis more`
  7595.                  c:\os2\bin\more.exe is newer than
  7596.                  c:\os2\cmds\more.com
  7597.                  427 D% _
  7598.  
  7599.                When you  pass arguments to a procedure on the command
  7600.             line, the  individual argument  words are paired up, one-
  7601.             by-one, with  the argument  names you gave.  If the shell
  7602.             runs out  of names  before it runs out of words, the last
  7603.             named argument gets all the remaining words:
  7604.  
  7605.                  427 D% proc xx(a, b)
  7606.                  428 D?   echo $#a $a
  7607.                  429 D?   echo $#b $b
  7608.                  430 D? end
  7609.  
  7610.  
  7611.  
  7612.                                      Page 116
  7613.  
  7614.                                                        Programming Constructs
  7615.  
  7616.  
  7617.                  431 D% xx now is the time
  7618.                  1 now
  7619.                  3 is the time
  7620.  
  7621.             If you  pass arguments  to a  procedure that doesn't take
  7622.             any, they're evaluated but quietly ignored.
  7623.  
  7624.                  If a  procedure does take an argument, it always get
  7625.             some value, even if it's zero words long.  So if you want
  7626.             to know  if you got passed a value, just count the number
  7627.             of words:
  7628.  
  7629.                  432 D% proc xx(a)
  7630.                  433 D?    echo $#a ">>$a<<"
  7631.                  434 D?    if (a == "") echo null argument!
  7632.                  435 D? end
  7633.                  436 D% xx
  7634.                  0 >><<
  7635.                  null argument!
  7636.  
  7637.                In a  more serious  vein, here's  a  simple  procedure
  7638.             definition  I   use  all  the  time  (I  have  it  in  my
  7639.             startup.csh file)  to implement  a real  quick and  dirty
  7640.             (but very easy to use!) personal phone index:
  7641.  
  7642.                  437 D% proc ppi(name)
  7643.                  438 D?    grep -i "$name" h:\phone
  7644.                  439 D? end
  7645.                  440 D% ppi hamilton
  7646.                  Hamilton Laboratories  508-358-5715  Fax: 508-358-
  7647.                  1113
  7648.  
  7649.             As you  add lines to your \phone file, you merely add any
  7650.             interesting search phrases or other tidbits onto the same
  7651.             line with  the person's  name.  Totally free format.  Add
  7652.             anything you  like and  search on  anything you  like and
  7653.             it's fast.
  7654.  
  7655.  
  7656.  
  7657.              Return Values
  7658.  
  7659.                Procedures are  also important  in expressions,  where
  7660.             it's generally  useful  to  think  of  the  procedure  as
  7661.             returning  a  value,  just  as  it  might  in  any  other
  7662.             language.   The type  and value  of what  you  choose  to
  7663.             return  is  arbitrary.    Here's  a  purely  mathematical
  7664.             example from finance.csh in the samples directory:
  7665.  
  7666.                  441 D% proc FV_PresentAmount(i, n)
  7667.                  442 D?    # Calculate the multiplier to convert $1
  7668.                  now to a
  7669.                  443 D?    #    future value, given interest rate i
  7670.                  444 D?     return 1/(1 + i/100)**n
  7671.  
  7672.  
  7673.  
  7674.                                      Page 117
  7675.  
  7676.      Programming Constructs
  7677.  
  7678.  
  7679.                  445 D? end
  7680.                  446 D% # Calculate the future value of $500 invested
  7681.                  447 D% # for 10 years at 8% interest.
  7682.                  448 D% calc 500*FV_PresentAmount(8, 10)
  7683.                  1079.462499
  7684.  
  7685.                If you  call a procedure that returns a value as if it
  7686.             were a command, whatever it returns is printed:
  7687.  
  7688.                  449 D% FV_PresentAmount 8 10
  7689.                  2.158925
  7690.  
  7691.  
  7692.  
  7693.             Recursion
  7694.  
  7695.                A procedure  can call other procedures or even itself.
  7696.             When a  procedure calls  itself, it's  called  recursion.
  7697.             Typical uses  of recursion are in cases where the problem
  7698.             itself is  recursive, or  self-replicating.  For example,
  7699.             here's a procedure to walk down two directory trees A and
  7700.             B that  are thought to be related and list any non-hidden
  7701.             files in  A that  are not in B.  (If you set nonohidden =
  7702.             1, it'll compare hidden files also.)
  7703.  
  7704.  
  7705.  
  7706.  
  7707.  
  7708.  
  7709.  
  7710.  
  7711.  
  7712.  
  7713.  
  7714.  
  7715.  
  7716.  
  7717.  
  7718.  
  7719.  
  7720.  
  7721.  
  7722.  
  7723.  
  7724.  
  7725.  
  7726.  
  7727.  
  7728.  
  7729.  
  7730.  
  7731.  
  7732.  
  7733.  
  7734.  
  7735.  
  7736.                                      Page 118
  7737.  
  7738.                                                        Programming Constructs
  7739.  
  7740.  
  7741.                  450 D% proc comparetrees(a, b)
  7742.                  451 D?    local i, f
  7743.                  452 D?    foreach i ($a\*)
  7744.                  453 D?       @ f = $i:t
  7745.                  454 D?       if (! -e $b\$f) then
  7746.                  455 D?          echo $b\$f is missing
  7747.                  456 D?       else
  7748.                  457 D?          if (-d $i) comparetrees $i $b\$f
  7749.                  458 D?       end
  7750.                  459 D?    end
  7751.                  460 D? end
  7752.                  461 D% comparetrees c:\src\projectx a:\src
  7753.  
  7754.                Notice that  i and f were declared as local variables.
  7755.             If the  variables were simply set variables, one instance
  7756.             of them  would be  shared by all the levels of recursion.
  7757.             In this particular example, that would still have worked,
  7758.             but only  because each  level calls  the next  only after
  7759.             anything involving f or i has been evaluated; it wouldn't
  7760.             matter if  f or  i was trampled by the next call.  Here's
  7761.             an example  where obviously  that would  not be  true:  a
  7762.             clumsy  attempt   at  a  ``post-order''  traversal  of  a
  7763.             directory tree:
  7764.  
  7765.                  462 D% proc traverse(a)   # Don't do it this way
  7766.                  463 D?    foreach i ($a\*)
  7767.                  464 D?      if (-d $i) traverse $i
  7768.                  465 D?      echo $i
  7769.                  466 D?    end
  7770.                  467 D? end
  7771.                  468 D% traverse . | more
  7772.  
  7773.                If you  carefully examine the output of this traverse,
  7774.             you'll see that subdirectories don't get listed properly:
  7775.             instead of  being listed by themselves, the name of their
  7776.             last child is listed twice.  For a correct result, try it
  7777.             again with  i defined  as a  local variable.    (Use  the
  7778.             <PageUp> key  to help you quickly re-enter the lines that
  7779.             stay the same.)
  7780.  
  7781.  
  7782.  
  7783.             Calling a Procedure
  7784.  
  7785.                As you  may have spotted, there are two ways to invoke
  7786.             a  procedure.     Sometimes,  the  arguments  are  inside
  7787.             parentheses, separated  by commas,  and sometimes they're
  7788.             not.  What's the difference?
  7789.  
  7790.                The difference is whether the context is an expression
  7791.             or a  command.   As discussed  when we  first  introduced
  7792.             expressions, the  shell always begins to parse statements
  7793.             by first  breaking them  up into  words.  That's fine for
  7794.             normal commands,  e.g., running an external utility.  And
  7795.  
  7796.  
  7797.  
  7798.                                      Page 119
  7799.  
  7800.      Programming Constructs
  7801.  
  7802.  
  7803.             it works  also when  you want to use a procedure as if it
  7804.             were a  command, just  typing the  name of  the procedure
  7805.             followed by  a list  of arguments  separated  by  spaces,
  7806.             e.g.,
  7807.  
  7808.                  469 D% proc power(a, b)
  7809.                  470 D?    return a**b
  7810.                  471 D? end
  7811.                  472 D% power 2 3
  7812.                  8
  7813.                  473 D% _
  7814.  
  7815.                But this style of parsing wouldn't be very suitable in
  7816.             those instances  where the  point is  to do  some kind of
  7817.             calculation or  expression evaluation.  So when the shell
  7818.             encounters something  that normally  takes an expression,
  7819.             e.g., following  the calc  keyword, or inside the test in
  7820.             an if  statement, it  shifts  to  a  different  style  of
  7821.             parsing, further  breaking up  the words  into tokens, so
  7822.             that ``*'' isn't misunderstood as a wildcard, so we don't
  7823.             need to  type spaces  around all the operators, so we can
  7824.             type variable  names without  having to  put a  ``$''  in
  7825.             front of  them and  so on.   All  of this  is so that the
  7826.             rules for  typing an expression can bear some resemblance
  7827.             to those  followed by other programming languages like C,
  7828.             Fortran, Pascal, etc.
  7829.  
  7830.                When we  call a  procedure from  within an expression,
  7831.             all these  same arguments still apply.  We want it to act
  7832.             pretty much like any other high level languages.  We want
  7833.             to be  able to pass it arbitrarily complex expressions as
  7834.             arguments.   We want  to be  able to  take the  value  it
  7835.             returns and  use that  value as  a term  in  still  other
  7836.             expressions.
  7837.  
  7838.                So there's  a real  problem:  to call a procedure from
  7839.             within  an  expression  and  pass  other  expressions  as
  7840.             arguments, we  need a way of separating one argument from
  7841.             the next (obviously, it can't be just a space as it would
  7842.             be when  the procedure  is used  as if it were a command)
  7843.             and for  separating the  whole  procedure  call  and  its
  7844.             arguments from  the rest  of the  expression.  That's why
  7845.             the common  high-level language  convention of separating
  7846.             arguments by  commas and  putting parentheses  around the
  7847.             whole list is used.  Here's an example of what that looks
  7848.             like:
  7849.  
  7850.                  473 D% calc 5.5 + power(2, 3)*9
  7851.                  77.500000
  7852.  
  7853.                If  you  try  using  a  procedure  as  a  command  but
  7854.             accidentally type  the argument  list  with  parenthesis,
  7855.             it's an error:
  7856.  
  7857.  
  7858.  
  7859.  
  7860.                                      Page 120
  7861.  
  7862.                                                        Programming Constructs
  7863.  
  7864.  
  7865.                  474 D% power(2, 3)
  7866.                  csh(line 470):  Couldn't evaluate expression
  7867.                  operands as numeric as required by the expression
  7868.                  operator.
  7869.                  > in power( "(", "2,", "3", ")" ) defined at line
  7870.                  469
  7871.                  < called from line 474
  7872.  
  7873.             The reason  this is  an error  is because, since this was
  7874.             typed as  a command,  the shell  took the words following
  7875.             the word  power as  literal arguments.   It couldn't tell
  7876.             you meant  this as  an expression.   Let's  redefine that
  7877.             procedure, putting  some echo  statements in  there so we
  7878.             can see what happened:
  7879.  
  7880.                  475 D% proc power(a, b)
  7881.                  476 D?   echo a is $a
  7882.                  477 D?   echo b is $b
  7883.                  478 D?   return a**b
  7884.                  479 D? end
  7885.                  480 D% power(2, 3)
  7886.                  a is (
  7887.                  b is 2, 3 )
  7888.                  csh(line 478):  Couldn't evaluate expression
  7889.                  operands as numeric as required by the expression
  7890.                  operator.
  7891.                  > in power( "(", "2,", "3", ")" ) defined at line
  7892.                  467
  7893.                  < called from line 480
  7894.  
  7895.             As  you  can  see,  the  expression  ``a**b''  failed  to
  7896.             evaluate properly because a was set to the first argument
  7897.             word, ``('',  and b  was set to a string concatenation of
  7898.             all the rest of the words.  Neither was a number.
  7899.  
  7900.                If you  want to  call a  procedure and  substitute the
  7901.             value back onto the command line even when the context is
  7902.             not an  expression, it  can be done, however.  One way is
  7903.             with command substitution:
  7904.  
  7905.                  481 D% echo `power 2 3`
  7906.                  a is 2 b is 3 8
  7907.  
  7908.                This is  a bit  expensive, though,  because the  shell
  7909.             will have  to create  a  new  thread  to  run  the  power
  7910.             procedure and  set up  a pipe to read the result.  And as
  7911.             you see,  if the  procedure also writes to stdout, you'll
  7912.             pick up that text also, probably unintentially.  Another,
  7913.             better way,  is to  use a  dollar sign  to introduce  the
  7914.             substitution just as if it was a variable substitution:
  7915.  
  7916.                  482 D% echo $power(2, 3)
  7917.                  a is 2
  7918.  
  7919.  
  7920.  
  7921.  
  7922.                                      Page 121
  7923.  
  7924.      Programming Constructs
  7925.  
  7926.  
  7927.                  b is 3
  7928.                  8
  7929.  
  7930.             Notice that  when use  the  dollar  sign-style  procedure
  7931.             reference, the  rest of the syntax is as if the procedure
  7932.             had been called from within an expression.  The arguments
  7933.             do need  to be  within parenthesis and they do need to be
  7934.             separated by  commas.  The reason is just the same one as
  7935.             for why  a procedure call in an expression has to be done
  7936.             this way:   without the parentheses, there'd be no way to
  7937.             tell where  the arguments  ended.  A nice benefit is that
  7938.             in the  argument list,  we get to use the full expression
  7939.             grammar:
  7940.  
  7941.                  483 D% echo $power(2, 3*sin(1/2))
  7942.                  a is 2
  7943.                  b is 1.438277
  7944.                  2.709970
  7945.  
  7946.  
  7947.  
  7948.             Shell Scripts
  7949.  
  7950.                Scripts are  a final  way of  bundling up  a series of
  7951.             statements to  be called  up and  executed  as  a  single
  7952.             command.   To create  a script, create a file with a .csh
  7953.             extension:
  7954.  
  7955.                  484 D% cat >trythis.csh
  7956.                  echo hello from trythis
  7957.                  ^Z
  7958.                  485 D% trythis
  7959.                  hello from trythis
  7960.  
  7961.                When you  tell the  shell to  run a  script, it  first
  7962.             creates a  new thread  to run  it.    This  is  partly  a
  7963.             holdover from original UNIX language definition, partly a
  7964.             response to  a provision  in OS/2 and NT for threads, but
  7965.             not a  fork mechanism and partly due to a genuine need to
  7966.             inexpensively separate  some of  the script's environment
  7967.             from that  of its caller.  (The next chapter has a longer
  7968.             discussion of threads.)
  7969.  
  7970.  
  7971.  
  7972.             Shell Script Arguments
  7973.  
  7974.                Arguments to  a shell  script are  passed to it as the
  7975.             argv variable.   argv  will be  a list  of any words that
  7976.             appeared on  the command  line following  the name of the
  7977.             shell script.   (You can access the name of the script as
  7978.             the scriptname  variable.)   You can access argv like any
  7979.             other variable:
  7980.  
  7981.  
  7982.  
  7983.  
  7984.                                      Page 122
  7985.  
  7986.                                                        Programming Constructs
  7987.  
  7988.  
  7989.                  486 D% cat >tryargv.csh
  7990.                  echo $#argv $argv
  7991.                  ^Z
  7992.                  487 D% tryargv hello how are you
  7993.                  4 hello how are you
  7994.  
  7995.                There  are  also  some  shorthand  forms  for  getting
  7996.             individual words  of argv.   $0 through $9 is the same as
  7997.             $argv[0] through  $argv[9].   (Remember that  unless  you
  7998.             have nullwords set, subscripting errors will be caught.)
  7999.  
  8000.  
  8001.  
  8002.             ignorestatus
  8003.  
  8004.                If  you   write  a   script  with  serially  connected
  8005.             statements the  only thing  that would cause the shell to
  8006.             quit before  it gets  to the  end would  be  an  explicit
  8007.             failure:   an application  name that couldn't be found, a
  8008.             child process  that terminated  with a  segment fault, or
  8009.             something else  of an equally serious nature.  Often in a
  8010.             script, that's  not what  you want:   you've  written the
  8011.             script with the expectation that everything will work (as
  8012.             you planned)  from one step to the next.  If something is
  8013.             wrong, you'd like the script to quit as soon as possible,
  8014.             before any damage is done.
  8015.  
  8016.                The way  you do  this is  by setting ignorestatus = 0,
  8017.             which means  you do  not want  to ignore the status codes
  8018.             coming back  to this thread from its children.  Here's an
  8019.             example in the main thread:
  8020.  
  8021.                  488 D% set ignorestatus = 0
  8022.                  489 D% rcode 10
  8023.                  10
  8024.                  csh:  The child process running 'rcode' exited with
  8025.                  a non-zero status = 10.
  8026.  
  8027.             In the  main thread,  the shell  will keep  on going  and
  8028.             prompt for  the next command because interactively that's
  8029.             most sensible.   The  shell  knows  to  do  this  because
  8030.             ignoreerrors =  1.   But in  a script,  errors cause  the
  8031.             shell to quit:
  8032.  
  8033.  
  8034.  
  8035.  
  8036.  
  8037.  
  8038.  
  8039.  
  8040.  
  8041.  
  8042.  
  8043.  
  8044.  
  8045.  
  8046.                                      Page 123
  8047.  
  8048.      Programming Constructs
  8049.  
  8050.  
  8051.                  490 D% cat >trythis.csh
  8052.                  calc ignoreerrors
  8053.                  set ignorestatus = 0
  8054.                  rcode 10
  8055.                  echo does^'t print
  8056.                  ^Z
  8057.                  491 D% trythis
  8058.                  0
  8059.                  10
  8060.                  csh(d:\doug\trythis.csh:line 3): The child process
  8061.                  running 'rcode' exited with a non-zero status = 10.
  8062.                  > in d:\doug\trythis.csh
  8063.                  < called from line 491
  8064.                  csh:  The csh script file
  8065.                  'd:\doug\samples\trythis.csh' exited with a non-zero
  8066.                  status = 10.
  8067.  
  8068.             Notice that  in this  case we  got two messages, one from
  8069.             the threads  executing the  script and  one from the main
  8070.             thread, reporting what the script returned.  Let's return
  8071.             to the normal mode of ignoring status:
  8072.  
  8073.                  492 D% set ignorestatus = 1
  8074.  
  8075.  
  8076.  
  8077.             source statement
  8078.  
  8079.                The examples  so  far  have  shown  how  a  script  is
  8080.             normally run  somewhat isolated in a separate thread.  It
  8081.             is also  possible to  run a script in your current thread
  8082.             using the source statement.  You might want to do this if
  8083.             you wanted  to the script to change your current thread's
  8084.             private variables  or its  current directories  or  disk.
  8085.             Here's an example to showing how a sourced script runs in
  8086.             the same thread:
  8087.  
  8088.                  493 D% cat >trythis.csh
  8089.                  echo argv = $argv, threadid = $threadid
  8090.                  ^Z
  8091.                  494 D% echo $threadid
  8092.                  6
  8093.                  495 D% trythis hello world
  8094.                  argv = hello world, threadid = 7
  8095.                  496 D% source trythis hello world
  8096.                  argv = hello world, threadid = 6
  8097.                  498 D% _
  8098.  
  8099.             Notice how the argv argument vector is set up the same in
  8100.             either case.   Also,  notice that  the  statement  number
  8101.             skipped by  one.  When you source a script, the effect is
  8102.             precisely as  if you typed those lines in directly to the
  8103.             shell.   The lines  read by  source are even entered into
  8104.             the history list:
  8105.  
  8106.  
  8107.  
  8108.                                      Page 124
  8109.  
  8110.                                                        Programming Constructs
  8111.  
  8112.  
  8113.                  498 D% h 5
  8114.                      494  echo $threadid
  8115.                      495  trythis hello world
  8116.                      496  source trythis hello world
  8117.                      497  echo argv = $argv, threadid = $threadid
  8118.                      498  h 5
  8119.  
  8120.  
  8121.  
  8122.             Caution:  Labels and Gotos
  8123.  
  8124.                We haven't  mentioned labels  and  gotos  yet  but  it
  8125.             probably isn't  a surprise  that the C shell allows them.
  8126.             Indeed:
  8127.  
  8128.                  499 D% cat >trythis.csh
  8129.                  goto next
  8130.                  echo this does not print
  8131.                  next: echo this prints
  8132.                  ^Z
  8133.                  500 D% trythis
  8134.                  this prints
  8135.  
  8136.                If you  want to  use gotos  to labels,  you should  be
  8137.             aware that forward references can be little trickier than
  8138.             a more  conventional compiled  language.    The  C  shell
  8139.             allows you  to redefine a label anytime you like.  But if
  8140.             you type  a goto that refers to previously defined label,
  8141.             the shell  has no  way of  knowing that  you intend it to
  8142.             redefine it  up ahead.   You  can keep  running the  last
  8143.             example over  and over  this way  with exactly  the  same
  8144.             result:   because a  new thread is started each time with
  8145.             no prior definition of next, the shell knows it must be a
  8146.             forward reference.   But  imagine how repeatedly sourcing
  8147.             this script would fail in an infinite loop:
  8148.  
  8149.                  % source trythis
  8150.                  this prints
  8151.                  % source trythis
  8152.                  this prints
  8153.                  this prints
  8154.                  this prints
  8155.                  this prints
  8156.                  this prints
  8157.                  :
  8158.                  
  8159.  
  8160.             (Beware of  actually  trying  this:    you  may  find  it
  8161.             difficult to interrupt out of it.)
  8162.  
  8163.                The reason  sourcing the  script a  second time  turns
  8164.             into an  infinite loop  is that the label next is already
  8165.             defined after  the first  run.  The second time, when the
  8166.  
  8167.  
  8168.  
  8169.  
  8170.                                      Page 125
  8171.  
  8172.      Programming Constructs
  8173.  
  8174.  
  8175.             goto is read from the script, the history list would look
  8176.             something like this:
  8177.  
  8178.                  source trythis
  8179.                  goto next
  8180.                  echo does not print
  8181.                  next: echo this prints
  8182.                  source trythis
  8183.                  goto next
  8184.  
  8185.             What particularly gets the shell into a muddle is the way
  8186.             this recurses  indefinitely: each  time through the loop,
  8187.             it  recurses   through  an  another  level  of  sourcing.
  8188.             Ultimately, it  runs out of stack space and fails.   This
  8189.             is not a nice way to treat the shell!
  8190.  
  8191.                In general,  it's  hard  to  recommend  gotos  in  any
  8192.             programming language  nowadays; in a script you intend to
  8193.             run using source, they can be particularly nasty.
  8194.  
  8195.                The shell does automatically age labels and throw them
  8196.             away after  a while  even if they haven't been redefined.
  8197.             When it  discards a  label, it also discards any compiled
  8198.             statements it's  been holding  onto that  could have been
  8199.             executed only  by a goto to that label.  The cutoff point
  8200.             where the  shell begins  to discard  labels is set by the
  8201.             gotowindow variable.   Let's now clean up after ourselves
  8202.             and move along:
  8203.  
  8204.                  501 D% rm trythis.csh
  8205.  
  8206.  
  8207.  
  8208.             Interrupts
  8209.  
  8210.                Normally,  when   you  type   ^C,  you  interrupt  the
  8211.             foreground activity.   But  what if you were in the midst
  8212.             of a complex script and needed to do some kind of cleanup
  8213.             before you exited?  What if you wanted to be sure you had
  8214.             a chance  to delete  any temporary  files you  might have
  8215.             littered around?
  8216.  
  8217.                The solution is the onintr statement, which allows you
  8218.             to define  the action  to be  taken when  an interrupt is
  8219.             received.  It causes whatever's running to be interrupted
  8220.             all the  way back  up to  the block  in which  the onintr
  8221.             routine was  defined and  for the interrupt routine to be
  8222.             run in  that  current  thread.    Within  that  interrupt
  8223.             routine,  you   could,  for   example,  remove  all  your
  8224.             temporary files  and goto the end of the script or return
  8225.             a special  value from  a procedure or whatever else might
  8226.             be appropriate.
  8227.  
  8228.  
  8229.  
  8230.  
  8231.  
  8232.                                      Page 126
  8233.  
  8234.                                                        Programming Constructs
  8235.  
  8236.  
  8237.                  502 D% onintr echo hello
  8238.                  503 D% for i = 1 to 5 do
  8239.                  504 D?    echo $i
  8240.                  505 D?    sleep 1
  8241.                  506 D? end
  8242.                  1
  8243.                  ^C
  8244.                  hello
  8245.  
  8246.                Here's another  example, returning  from a  procedure.
  8247.             Note how  the value  returned (and  printed) is  the  one
  8248.             produced by the onintr statement.
  8249.  
  8250.                  507 D% proc foobar()
  8251.                  508 D?    onintr return 5
  8252.                  509 D?    for i = 1 to 5 do
  8253.                  510 D?        echo $i
  8254.                  511 D?        sleep 1
  8255.                  512 D?    end
  8256.                  513 D? return 2
  8257.                  514 D? end
  8258.                  515 D% foobar
  8259.                  1
  8260.                  ^C
  8261.                  5
  8262.  
  8263.                When execution  leaves the block in which an onintr is
  8264.             defined, the previous onintr (if any) again takes effect.
  8265.             Note that  a null  onintr  routine  does  not  mean  that
  8266.             interrupts are  ignored,  merely  that  after  processing
  8267.             bubbles back  up to  the  level  where  that  onintr  was
  8268.             defined, that  it will  continue with the next statement.
  8269.             Notice how, in this example, when the ^C is received when
  8270.             obviously execution  is stuck in the infinite loop inside
  8271.             bar, that the ``onintr goto xx'' causes a branch to xx in
  8272.             the same  block in  which the onintr was defined, not the
  8273.             xx in  the block  where execution  was going  on.   Also,
  8274.             notice that  once both procedures have been exited, we're
  8275.             back  to  the  same  onintr  routine  we  defined  a  few
  8276.             statements earlier.
  8277.  
  8278.                  516 D% proc foo()
  8279.                  517 D?    onintr goto xx
  8280.                  518 D?    bar
  8281.                  519 D?   xx:  echo this is foo
  8282.                  520 D? end
  8283.                  521 D% proc bar()
  8284.                  522 D?    while (1)   # Deliberately infinite loop
  8285.                  523 D?    end
  8286.                  524 D?   xx:  echo this is bar
  8287.                  525 D? end
  8288.                  526 D% foo
  8289.                  ^C
  8290.                  this is foo
  8291.  
  8292.  
  8293.  
  8294.                                      Page 127
  8295.  
  8296.      Programming Constructs
  8297.  
  8298.  
  8299.                  527 D% ^C
  8300.                  hello
  8301.                  527 D% _
  8302.  
  8303.  
  8304.  
  8305.             Masking Interrupts
  8306.  
  8307.                In  cases   where  you'd   like  to  simply  turn  off
  8308.             interrupts or  defer processing  them,  use  the  irqmask
  8309.             variable.   By default, it's set to 0, meaning interrupts
  8310.             will be  accepted immediately.   Setting  it to  1  means
  8311.             interrupts will  be deferred  until the  mask is  cleared
  8312.             again.   Setting it to 2 means interrupts will be totally
  8313.             ignored.
  8314.  
  8315.                irqmask is  a per-thread variable, meaning each thread
  8316.             can  independently   decide  how   it  will   respond  to
  8317.             interrupts.   Each new  thread  always  starts  out  with
  8318.             irqmask = 0 (interrupts enabled).
  8319.  
  8320.  
  8321.  
  8322.  
  8323.  
  8324.  
  8325.  
  8326.  
  8327.  
  8328.  
  8329.  
  8330.  
  8331.  
  8332.  
  8333.  
  8334.  
  8335.  
  8336.  
  8337.  
  8338.  
  8339.  
  8340.  
  8341.  
  8342.  
  8343.  
  8344.  
  8345.  
  8346.  
  8347.  
  8348.  
  8349.  
  8350.  
  8351.  
  8352.  
  8353.  
  8354.  
  8355.  
  8356.                                      Page 128
  8357.  
  8358.                                                        Programming Constructs
  8359.  
  8360.  
  8361.             
  8362.  
  8363.  
  8364.  
  8365.  
  8366.  
  8367.  
  8368.  
  8369.  
  8370.  
  8371.  
  8372.  
  8373.  
  8374.  
  8375.  
  8376.  
  8377.  
  8378.  
  8379.  
  8380.  
  8381.  
  8382.  
  8383.  
  8384.  
  8385.  
  8386.  
  8387.  
  8388.  
  8389.  
  8390.  
  8391.  
  8392.  
  8393.  
  8394.  
  8395.  
  8396.  
  8397.  
  8398.  
  8399.  
  8400.  
  8401.  
  8402.  
  8403.  
  8404.  
  8405.  
  8406.  
  8407.  
  8408.  
  8409.  
  8410.  
  8411.  
  8412.  
  8413.  
  8414.  
  8415.  
  8416.  
  8417.  
  8418.                                      Page 129
  8419.  
  8420.      Scheduling
  8421.  
  8422.  
  8423.             
  8424.  
  8425.  
  8426.                                    Scheduling
  8427.  
  8428.  
  8429.  
  8430.  
  8431.             Foreground Activities
  8432.  
  8433.                Whenever you  type any  command,  the  shell's  normal
  8434.             behavior is  to start  up that child activity and then go
  8435.             to sleep  waiting for  it complete.  This is a foreground
  8436.             activity.   If you  start something  and then  decide you
  8437.             want to stop it, type Control-C, which wakes up the shell
  8438.             and causes it to stop the foreground activities.
  8439.  
  8440.                Under OS/2,  Hamilton C shell can tell the difference+
  8441.             between    full-screen,    text-windowable    and    full
  8442.             Presentation Manager applications and properly spawns new
  8443.             screen groups  for applications  that can't  run  in  the
  8444.             shell's window.   For  example, typing  the name  of  the
  8445.             Presentation Manager control panel:
  8446.  
  8447.                  527 D% pmcpl
  8448.  
  8449.             will (or  at least,  should) cause  the control  panel to
  8450.             appear in a new window.
  8451.  
  8452.                Similarly, under Windows NT, if you type the name of a
  8453.             graphical application,  the C  shell will  recognize that
  8454.             based on an actual examination of the file itself.
  8455.  
  8456.                Under both  OS/2 and  Windows NT,  when you  start  an
  8457.             application that  needs a  new window,  the  shell  comes
  8458.             right back for the next command.
  8459.  
  8460.                Also, if  the child  is a  a graphical application and
  8461.             stdout or  stderr is tied to the console window where the
  8462.             C shell's  running, the  C  shell  recognizes  that  that
  8463.             handle won't be inheritable by the child and instead will
  8464.             create a pipe.  It'll give the write end to the child and
  8465.             ____________________
  8466.             + Actually, under  OS/2, the  shell depends  on the  .exe
  8467.               file being  properly marked with  the application type.
  8468.               Unfortunately, not   all  developers yet know about and
  8469.               obey this rule.  For example, in some releases of OS/2,
  8470.               even IBM  forgot to  mark some applications such as the
  8471.               control panel.   Unmarked applications are, by default,
  8472.               started full-screen;  a PM  application that's  started
  8473.               this way  dies immediately.  If you spot this behavior,
  8474.               you should  mark the  offending application  using  the
  8475.               markexe  utility.     (Type  ``markexe  -h''  for  more
  8476.               information.)
  8477.  
  8478.  
  8479.  
  8480.                                      Page 130
  8481.  
  8482.                                                                    Scheduling
  8483.  
  8484.  
  8485.             create a  background  thread  in  the  C  shell  to  read
  8486.             anything coming  back over  the pipe  from the  child and
  8487.             copy it  to the console window.  This means that with the
  8488.             C shell, you can still use ordinary printf's in a OS/2 PM
  8489.             or NT graphical application and not lose any output.
  8490.  
  8491.  
  8492.  
  8493.             Background Activities
  8494.  
  8495.                If you  want to  run something  but don't want to wait
  8496.             for it complete, just type an ampersand at the end of the
  8497.             statement:
  8498.  
  8499.                  528 D% wc hello.c >linecnt &
  8500.                  1
  8501.                  529 D% _
  8502.  
  8503.             This creates  a child  process to  run word  count in the
  8504.             background, with  its output  directed to  a file.    The
  8505.             ``1'' message means that a new background job (job 1) has
  8506.             been spawned to process the command while you continue to
  8507.             work.   The job  starts as  a new thread.  If, as in this
  8508.             case, a  separate process  is needed,  that  thread  will
  8509.             create it  with a  DosExecPgm call to the OS/2 kernel (or
  8510.             CreateProcess  call   to  the   Windows  NT   kernel,  as
  8511.             appropriate), then  exit.   Each new  thread, process  or
  8512.             screen group spawned by a background job will inherit its
  8513.             parent's job  number.  Every time a new background job is
  8514.             created, the job number is incremented.
  8515.  
  8516.                The use  of i/o  redirection  in  combination  with  a
  8517.             background activity  is not  accidental.    If  it's  not
  8518.             redirected, it  goes to  your terminal,  intermixing with
  8519.             the output  of any  foreground activities.  Occasionally,
  8520.             that might be exactly what you want.  For example, here's
  8521.             a timer to wake you up in 5 minutes (300 seconds):
  8522.  
  8523.                  529 D% (sleep 300; echo ^aWake Up, Sleepyhead.) &
  8524.                  2
  8525.                  :
  8526.                  :
  8527.                  Beep
  8528.                  Wake Up, Sleepyhead.
  8529.  
  8530.                The ampersand  works consistently for things that need
  8531.             a new window:
  8532.  
  8533.                  530 D% pmcpl &
  8534.                  3
  8535.                  531 D% _
  8536.  
  8537.             A new  job starts  up and announces itself, then realizes
  8538.             that the  control panel  has to  be  run  in  a  separate
  8539.  
  8540.  
  8541.  
  8542.                                      Page 131
  8543.  
  8544.      Scheduling
  8545.  
  8546.  
  8547.             session.  Once it's started the child session, the thread
  8548.             exits and  its children  are adopted by its parent thread
  8549.             and child is left running as job 3.
  8550.  
  8551.                Under both  OS/2 and Windows NT, background activities
  8552.             are,  in  a  sense,  detached:    typing  Ctrl-C  doesn't
  8553.             interrupt  them   (unless  they   explicitly  ask  to  be
  8554.             notified.)   You can  start a  large number of background
  8555.             activities  and  check  on  their  status  using  the  ps
  8556.             (process status) command.  Here's what you'd see on OS/2;
  8557.             the output under NT would be fairly similar.
  8558.  
  8559.                  531 D% ps
  8560.                  Job     ID      Parent      State          Activity
  8561.                  -       t1      -           running
  8562.                  interrupt_handler
  8563.                  -       t2      t1          running
  8564.                  thread_cleanup
  8565.                  -       t3      t1          running
  8566.                  process_cleanup
  8567.                  -       t4      t1          running
  8568.                  screen_cleanup
  8569.                  -       t5      t1          running
  8570.                  keyboard_reader
  8571.                  -       t6      t1          running
  8572.                  main_thread
  8573.                  -       t7      t1          running
  8574.                  console_io
  8575.                  3       s33     t6          running        pmcpl
  8576.  
  8577.                Threads 1  through 4  always run  in  the  background.
  8578.             Each spends most of the time asleep, waking up to do some
  8579.             housekeeping only  when an interrupt or the signal that a
  8580.             child activity  has completed  is received.   Thread 5 is
  8581.             dedicated to  reading characters  from  the  keyboard  on
  8582.             request from  other threads.   Thread 6 is the foreground
  8583.             command processor.  Thread 7 was spawned when the C shell
  8584.             realized that pmcpl is a graphical application and that a
  8585.             pipe would be needed to capture any stdio output from the
  8586.             child.  Other entries in the ps report come and go as you
  8587.             type commands.
  8588.  
  8589.                If you  want  to  explicitly  terminate  a  background
  8590.             activity, use the kill command.  But do keep in mind that
  8591.             under NT,  there are two ways to kill a process:  If it's
  8592.             a console  (text window)  application, it  can be done by
  8593.             sending it  a Ctrl-C  signal; that's  what kill  does  by
  8594.             default.   But if  it's a  graphical application,  it can
  8595.             only be  done using  the TerminateProcess  call,  a  very
  8596.             brute force way of killing something; any DLL's that were
  8597.             being used by that process will not any notification that
  8598.             the process  has died  and, thus, will not know to do any
  8599.             cleanup they might normally do.
  8600.  
  8601.  
  8602.  
  8603.  
  8604.                                      Page 132
  8605.  
  8606.                                                                    Scheduling
  8607.  
  8608.  
  8609.                  532 D% kill 3
  8610.                  533 D% ps
  8611.                  Job     ID      Parent      State          Activity
  8612.                  -       t1      -           running
  8613.                  interrupt_handler
  8614.                  -       t2      t1          running
  8615.                  thread_cleanup
  8616.                  -       t3      t1          running
  8617.                  process_cleanup
  8618.                  -       t4      t1          running
  8619.                  screen_cleanup
  8620.                  -       t5      t1          running
  8621.                  keyboard_reader
  8622.                  -       t6      t1          running
  8623.                  main_thread
  8624.                  -       t7      t1          running
  8625.                  console_io
  8626.  
  8627.  
  8628.  
  8629.             Variables and Threads
  8630.  
  8631.                User-defined variables  are shared  between all active
  8632.             threads unless they're declared as local:  if one changes
  8633.             a variable's  value, the  other threads  see that  change
  8634.             immediately.     Because  the   individual  threads   run
  8635.             asynchronously, this  can cause  some surprising results.
  8636.             In  this   example,  the  foreground  thread  spawns  new
  8637.             background threads  and increments  the variable i faster
  8638.             than the  children can  execute.   By the  time  any  the
  8639.             children actually  start, the loop has finished and every
  8640.             thread sees i as having the value 5.
  8641.  
  8642.                  534 D% for i = 1 to 3 do
  8643.                  535 D?    echo $i &
  8644.                  536 D? end
  8645.                  4
  8646.                  5
  8647.                  6
  8648.                  537 D% 5
  8649.                  5
  8650.                  5
  8651.  
  8652.                One solution  is to  use the  eval  statement.    eval
  8653.             parses the  text  it's  passed  at  run-time,  after  any
  8654.             variable substitutions  have  been  done.    Because  the
  8655.             ampersand is inside the quotes, its special meaning isn't
  8656.             detected until run-time.
  8657.  
  8658.                  537 D% for i = 1 to 3 do
  8659.                  538 D?    eval "echo $i &"
  8660.                  539 D? end
  8661.                  7
  8662.                  8
  8663.  
  8664.  
  8665.  
  8666.                                      Page 133
  8667.  
  8668.      Scheduling
  8669.  
  8670.  
  8671.                  9
  8672.                  540 D% 1
  8673.                  2
  8674.                  3
  8675.  
  8676.                A better solution is to make i a local variable, since
  8677.             locals are  snapshotted and  copied  when  the  child  is
  8678.             spawned:
  8679.  
  8680.                  540 D% local i;  for i = 1 to 3 do
  8681.                  541 D%    echo $i &
  8682.                  542 D% end
  8683.                  10
  8684.                  11
  8685.                  12
  8686.                  543 D% 1
  8687.                  2
  8688.                  3
  8689.  
  8690.  
  8691.  
  8692.             Re-entrancy
  8693.  
  8694.                Threads also introduce the possibility of re-entrancy.
  8695.             In the  next example,  we define  a procedure for summing
  8696.             all the  integers 1  to n.   Notice that it works fine if
  8697.             it's run  by itself,  but gives  the wrong answers if two
  8698.             threads try to run it simultaneously:
  8699.  
  8700.                  543 D% proc sum(n)
  8701.                  544 D?    @ s = 0
  8702.                  545 D?    for i = 1 to n do
  8703.                  546 D?       @ s += i
  8704.                  547 D?    end
  8705.                  548 D? end
  8706.                  549 D% sum 100
  8707.                  5050
  8708.                  550 D% sum 100 &; sum 100
  8709.                  13
  8710.                  6780
  8711.                  551 D% 7177
  8712.  
  8713.                Here  also,  the  solution  is  simply  to  include  a
  8714.             statement defining i and s as local inside the procedure.
  8715.  
  8716.  
  8717.  
  8718.             Threads:  An advanced discussion
  8719.  
  8720.                In  building   Hamilton  C   shell,  a  conscious  and
  8721.             fundamental decision  was made  to use  threads  in  many
  8722.             situations  where   earlier  shells  might  have  created
  8723.             separate processes.   The  result is  a dramatically more
  8724.  
  8725.  
  8726.  
  8727.  
  8728.                                      Page 134
  8729.  
  8730.                                                                    Scheduling
  8731.  
  8732.  
  8733.             responsive tool  albeit one  with  some  subtle  semantic
  8734.             differences from the original.
  8735.  
  8736.                The  UNIX  C  shell  language  definition  called  for
  8737.             individual stages  of a  pipeline, command  substitutions
  8738.             and scripts  each to  be run in a separate process cloned
  8739.             by forking  the main  process.   Using forking, the child
  8740.             inherited all  of its  parent's state (current directory,
  8741.             open file handles, environmental and set variables, etc.)
  8742.             but any  changes it made only affected itself.  On a UNIX
  8743.             system with  paging hardware and the fork mechanism built
  8744.             into the kernel, it's pretty fast.
  8745.  
  8746.                But OS/2 and the NT Win32 api's do not have fork+, and
  8747.             trying to recreate precisely this language semantic under
  8748.             OS/2  or   NT  would   have  been   foolishly  expensive,
  8749.             potentially adding  several seconds  to the  startup time
  8750.             each time you invoked a shell script.  On the other hand,
  8751.             these systems  do offer threads.  A process can have lots
  8752.             of threads  and each  one can  run along at its own pace.
  8753.             When a thread calls the kernel to do something that takes
  8754.             a long  time (e.g.,  a disk  read), it  goes to sleep and
  8755.             doesn't wake  up until the data's ready.  When one thread
  8756.             goes to sleep, the kernel looks around for another that's
  8757.             ready to  run.  By using threads, it's possible to ensure
  8758.             that if  one thing's  got to  wait, that  won't  hold  up
  8759.             everything else.
  8760.  
  8761.                Threads turn  out  to  be  even  faster  than  a  fork
  8762.             (regardless of the hardware), because the amount of state
  8763.             information  associated   with  a  thread  is  so  little
  8764.             compared to  that of a process.  As viewed by the kernel,
  8765.             a thread  ``owns'' only  a register  set, a  stack and an
  8766.             instruction pointer.   Everything  else, memory,  current
  8767.             directories, etc.,  is shared  among all the threads in a
  8768.             process.   This means  creating a thread is very fast, as
  8769.             is switching between threads.
  8770.  
  8771.                On the  other hand,  using threads  to best  advantage
  8772.             imposed some  significant design challenges in Hamilton C
  8773.             shell.   Certainly, for  example, few  would consider  it
  8774.             acceptable if  a script  running in  the background could
  8775.             >Boom< change  your foreground current disk!  The problem
  8776.             was to  create a  way for  threads to cooperatively share
  8777.             the process  resources but  without giving  away all  the
  8778.             performance advantage we'd started with by using threads.
  8779.             Also, some of the elegance of threads is the idea you can
  8780.             ____________________
  8781.             + The decision  not to provide a fork semantic under OS/2
  8782.               was  probably  forced  by  the  decision  that  initial
  8783.               releases of  OS/2  would  run  on  286-based  machines.
  8784.               Lacking paging  hardware, a  fork on a 286 would likely
  8785.               have been unacceptably slow, no matter how the software
  8786.               was designed.
  8787.  
  8788.  
  8789.  
  8790.                                      Page 135
  8791.  
  8792.      Scheduling
  8793.  
  8794.  
  8795.             keep creating new ones.  Each is just like the next:  any
  8796.             given thread  can run  just as  complex a  program as the
  8797.             next and each can spawn new threads.  It would be a shame
  8798.             to lose  that recursive  characteristic by  clumsiness in
  8799.             the language design.
  8800.  
  8801.                Starting with a clean sheet of paper, our solution was
  8802.             a highly  multi-threaded architecture.  It expects you to
  8803.             start lots  of threads:   stages  in a  pipe,  background
  8804.             activities, etc.   To  our knowledge,  no  other  command
  8805.             processor  on   any  system   employs  this   technology.
  8806.             Certainly, all  the code  in  Hamilton  C  shell  is  re-
  8807.             entrant:   there is  a  minimum  of  global,  statically-
  8808.             allocated data; the few variables that are global tend to
  8809.             be pointers to the roots of various dynamically-allocated
  8810.             information  trees   for  managing   variables,  threads,
  8811.             processes, file  handles and  other resources.   When the
  8812.             shell creates  a new  thread, it  creates the appropriate
  8813.             records and  links them  in.   Some characteristics given
  8814.             the new  thread are  inherited from  it's parent and some
  8815.             always get set to specific defaults.
  8816.  
  8817.                Shared variables  and other  resources are semaphored:
  8818.             before using  a resource,  a  thread  requests  it;    if
  8819.             several  resources  are  needed  simultaneously,  they're
  8820.             always requested  in the  same order  to avoid deadlocks.
  8821.             Critical resources  are  held  only  for  short  periods.
  8822.             There's no  polling anywhere.   ``Handle'' mechanisms are
  8823.             used so  that, e.g.,  a thread  can decide if its current
  8824.             disk and  directories are  set up  by simply comparing an
  8825.             integer.   Path hashing  structures  are  shared  with  a
  8826.             ``copy  on   write''  mechanism   in  case   they  change
  8827.             directories and  need slightly different hash structures.
  8828.             Any thread  can do what any other can: compile or execute
  8829.             an arbitrarily  complex C  shell program or even spawn or
  8830.             pipe child threads.
  8831.  
  8832.                Given the  enormous advantage  offered by  threads and
  8833.             the unique technology we've developed to exploit them, we
  8834.             expect Hamilton C shell should easily outperform any UNIX
  8835.             shell on comparable hardware.
  8836.  
  8837.  
  8838.  
  8839.  
  8840.  
  8841.  
  8842.  
  8843.  
  8844.  
  8845.  
  8846.  
  8847.  
  8848.  
  8849.  
  8850.  
  8851.  
  8852.                                      Page 136
  8853.  
  8854.                                                           Order of Evaluation
  8855.  
  8856.  
  8857.             
  8858.  
  8859.  
  8860.                                Order of Evaluation
  8861.  
  8862.  
  8863.                Finally, to  put everything  in perspective,  here's a
  8864.             summary of  roughly the  procedure by  which the  C shell
  8865.             reads, parses and evalutes your commands:
  8866.  
  8867.             1.   The command  is read.   If  stdin appears  to  be  a
  8868.                  keyboard, the command line editing routines are used
  8869.                  to read  a keystroke  at a  time, entering them into
  8870.                  the command  buffer and  doing whatever  editing  is
  8871.                  indicated.    Otherwise,  the shell  simply uses the
  8872.                  kernel's DosRead function to read small chunks until
  8873.                  the end of the statement has been found.
  8874.  
  8875.             2.   History substitution  is done.  The ``!'' and ``%''-
  8876.                  style history references are expanded.
  8877.  
  8878.             3.   The text  is broken  up into separate words.  Unless
  8879.                  it's part  of a quoted string, white space (tabs and
  8880.                  spaces)  separates   words.    Also,  these  special
  8881.                  strings are  interpreted as  separate words  even if
  8882.                  they're run together with other text:
  8883.  
  8884.                  &   |   ;   >   <   (   )   &&   ||   >>   <<   >&
  8885.                  >!   >&!
  8886.  
  8887.             4.   The command  is added to the history list.  The fact
  8888.                  that this  is done after the text has been broken up
  8889.                  into separate words explains why the commands in the
  8890.                  history list  will look a bit different than the way
  8891.                  you typed  them.   It's done  this way on purpose so
  8892.                  that you  can refer  to individual words in previous
  8893.                  commands, e.g.,  with ``!$''  to get  just the  last
  8894.                  word of the last command.
  8895.  
  8896.             5.   The command  is compiled into an internal form using
  8897.                  a recursive descent parser, recognizing the language
  8898.                  constructs and  whether a given portion of a command
  8899.                  is really an expression or just a series of words.
  8900.  
  8901.                  Compilation at this stage is at the level of a whole
  8902.                  construct, e.g.,  a whole  foreach statement or proc
  8903.                  definition and everything inside it.  That's so that
  8904.                  every time  through a loop or every time a procedure
  8905.                  is run,  the  shell  won't  waste  time  recompiling
  8906.                  statements that  could have  been compiled the first
  8907.                  time.   Also, aliases are expanded at this stage and
  8908.                  some  minor   optimizations  are  down,  e.g.,  pre-
  8909.                  compiling  static  patterns  appearing  in  pattern-
  8910.                  matching expressions, etc.
  8911.  
  8912.  
  8913.  
  8914.                                      Page 137
  8915.  
  8916.      Order of Evaluation
  8917.  
  8918.  
  8919.             6.   The internal  form is executed.  The various quoting
  8920.                  and  other  substitution  activities  are  done,  in
  8921.                  effect, in this order:
  8922.  
  8923.                  a.   Threads are  spawned for  separate stages  of a
  8924.                       pipeline or  for background  execution.  That's
  8925.                       to avoid  serializing any  blocking events  as,
  8926.                       for example,  the shell  hits the disk, looking
  8927.                       through the  search path  for executable files,
  8928.                       etc.    By  spawning  separate  threads,  those
  8929.                       blocking events can be overlapped.
  8930.  
  8931.                  b.   I/O redirection  is performed.  If the filename
  8932.                       being redirected to/from is actually a wildcard
  8933.                       or a command or some kind of substitution, that
  8934.                       word will be expanded.
  8935.  
  8936.                  c.   Single and double quoted strings are processed.
  8937.                       If the  quoted  string  contains  any  wildcard
  8938.                       characters, they're  escaped  so  that  they'll
  8939.                       appear as  literal characters  when wildcarding
  8940.                       is done  but still  be  unescaped  right  after
  8941.                       that.
  8942.  
  8943.                       In the  compiled internal  form,  double-quoted
  8944.                       strings   containing    variable   or   command
  8945.                       substitutions are  already specially  broken up
  8946.                       to look,  at this  stage, like a series double-
  8947.                       quoted strings  and substitutions  concatenated
  8948.                       together.
  8949.  
  8950.                  d.   Variable and command substitutions are done.
  8951.  
  8952.                  e.   Wildcarding is done.
  8953.  
  8954.                  f.   Escape characters are processed.
  8955.  
  8956.                  g.   The series of words is passed to the command as
  8957.                       arguments.   (It's at  this point,  if it's  an
  8958.                       eval command,  that the argument text is passed
  8959.                       back  through   the  parser  and  then  to  the
  8960.                       evaluation logic)
  8961.  
  8962.                       Commands are searched for in this order:
  8963.  
  8964.                       (1)  User-defined procedures.
  8965.  
  8966.                       (2)  Built-in procedures and commands.
  8967.  
  8968.                       (3)  External commands,  searched  for  in  the
  8969.                            PATH directories in this order within each
  8970.                            directory:
  8971.  
  8972.                               .csh   .exe   .com   .cmd   .bat
  8973.  
  8974.  
  8975.  
  8976.                                      Page 138
  8977.  
  8978.                                                           Order of Evaluation
  8979.  
  8980.  
  8981.                            (.bat files can be run only under OS/2 2.x
  8982.                            or Windows NT.)
  8983.  
  8984.             7.   The internal  form of  each  compiled  statement  is
  8985.                  discarded once  it's  no  longer  needed,  i.e.,  if
  8986.                  there's no  way you  might invoke  that code  from a
  8987.                  later statement.
  8988.  
  8989.                  For example,  once  you  define  a  procedure,  it's
  8990.                  always accessible;  you can  call it at any time, so
  8991.                  that compiled  code is  never discarded  unless  you
  8992.                  redefine the procedure or explicitly unproc it.  But
  8993.                  an ordinary  statement typed  at  the  command  line
  8994.                  could  be   re-run  (without  re-entering  it  using
  8995.                  history or  by retyping it) only if it was part of a
  8996.                  larger control  structure or  if there  was a way to
  8997.                  goto it,  meaning there  would have  to have  been a
  8998.                  label preceding it.
  8999.  
  9000.  
  9001.  
  9002.  
  9003.  
  9004.  
  9005.  
  9006.  
  9007.  
  9008.  
  9009.  
  9010.  
  9011.  
  9012.  
  9013.  
  9014.  
  9015.  
  9016.  
  9017.  
  9018.  
  9019.  
  9020.  
  9021.  
  9022.  
  9023.  
  9024.  
  9025.  
  9026.  
  9027.  
  9028.  
  9029.  
  9030.  
  9031.  
  9032.  
  9033.  
  9034.  
  9035.  
  9036.  
  9037.  
  9038.                                      Page 139
  9039.  
  9040.      Customizing the Shell
  9041.  
  9042.  
  9043.             
  9044.  
  9045.  
  9046.                               Customizing the Shell
  9047.  
  9048.  
  9049.                Depending on  your tastes and what you're used to (and
  9050.             whether you  come from  a  DOS  or  a  UNIX  background),
  9051.             Hamilton C  shell can  be customized in a number of ways.
  9052.             This section will outline:
  9053.  
  9054.                1.  Various  options  you  have  when  installing  the
  9055.                    shell, including  setting it  up  as  the  default
  9056.                    command processor,
  9057.  
  9058.                2.  How shell starts up, and how it uses the login.csh
  9059.                    and startup.csh files,
  9060.  
  9061.                3.  How to  set the  environmental  variables,  screen
  9062.                    colors and the prompt strings,
  9063.  
  9064.                4.  How to create aliases you always want available,
  9065.  
  9066.                5.  Customizing  the   cd  command   and  how  history
  9067.                    references work, and
  9068.  
  9069.                6.  Telling the shell how it should respond to certain
  9070.                    special situations.
  9071.  
  9072.  
  9073.  
  9074.             Installation Options
  9075.  
  9076.                You have  a fair  amount of  choice  about  where  the
  9077.             various files  associated with  Hamilton C  shell go  and
  9078.             also about  how it starts up.  You won't necessarily want
  9079.             to fool  with all  this when you first install the shell,
  9080.             but you  may want  to look  at some  of this as you get a
  9081.             sense of your own preferences.
  9082.  
  9083.                The C  shell .exe  and .csh  files can  go anywhere as
  9084.             long as they're on your search path.  Most people find it
  9085.             most convenient to keep them in a separate directory.  We
  9086.             do suggest  it be  ahead of  the directory containing the
  9087.             standard more.com  on your search path since we provide a
  9088.             new, vastly improved more.
  9089.  
  9090.                You choose any directory on any drive as your ``home''
  9091.             directory.   The significance of a home directory is that
  9092.             the shell  will make  references to  it or relative to it
  9093.             very  convenient  using  the  ``~''  wildcard  character.
  9094.             Also,  this  is  where  the  shell  will  look  for  your
  9095.             login.csh and  startup.csh files.   If HOME isn't defined
  9096.             in the  environment when the shell starts up, it defaults
  9097.  
  9098.  
  9099.  
  9100.                                      Page 140
  9101.  
  9102.                                                         Customizing the Shell
  9103.  
  9104.  
  9105.             to the  current directory.   It's usually most convenient
  9106.             to define the HOME variable in your config.sys but if you
  9107.             prefer, you  can pass it to the shell on the command line
  9108.             using ``-C  setenv HOME=...''   (The  ``-C''  means  what
  9109.             follows is a command.)
  9110.  
  9111.                Additional customization  is  usually  done  with  the
  9112.             login.csh and startup.csh files.
  9113.  
  9114.  
  9115.  
  9116.             Installing as the Default OS/2 Command Processor
  9117.  
  9118.                OS/2 gives  whatever  default  command  processor  you
  9119.             specify on  the PROTSHELL line of your config.sys special
  9120.             privileges to  change its  own title  bar and, under OS/2
  9121.             1.3 or  2.x, its  own icon.   This can be quite useful if
  9122.             you have  a lot  of copies of the shell running minimized
  9123.             and you'd like to know what they're doing.
  9124.  
  9125.                Under  OS/2   1.1  or   1.2,  the  C  shell  uses  the
  9126.             undocumented DosSMSetTitle kernel api entry to change its
  9127.             own  title;   under  1.3   or  2.x,   it  uses   the  new
  9128.             WinSetTitleAndIcon api to change both the title and icon.
  9129.             Unfortunately, these  api entries  are disabled if you're
  9130.             not running  in a  window  whose  root  process  was  the
  9131.             default command processor.
  9132.  
  9133.                To  install   the  C  shell  as  the  default  command
  9134.             processor,  follow   the  instructions   given   in   the
  9135.             installation section  of this manual.  In a nutshell, the
  9136.             idea is  to replace  the reference  to  cmd.exe  and  any
  9137.             parameters to  cmd.exe  on  the  PROTSHELL  or  OS2_SHELL
  9138.             (under 2.x)  line with  the full  pathname of the C shell
  9139.             plus a ``-L'' option to indicate it's a login shell.
  9140.  
  9141.                Next, fixup the entries for cmd.exe and the C shell in
  9142.             the Group-Main  or Start  Programs menus.   To  make it a
  9143.             default command  processor, the  C shell  must be  listed
  9144.             with an  ``*'' (asterisk)  for a  pathname (on the ``Path
  9145.             and file  name:'' line  if you  pull-down ``Program'' and
  9146.             select ``Properties...'  in Group-Main) or else the title
  9147.             bar and  icon changes  will be  disabled.  Also, for some
  9148.             reason, if you specify any startup parameters (other than
  9149.             ``/K "%*"''), that  also  disables  the  title  and  icon
  9150.             changes.      (The   ``/K "%*"''   option   has   special
  9151.             significance for  the default  command processor  and  is
  9152.             used when OS/2 boots up if it finds a startup.cmd file in
  9153.             the root directory; otherwise, it's ignored.)
  9154.  
  9155.                Conversely, you  have to  change the asterisk path and
  9156.             any arguments  for the cmd.exe entries to the actual path
  9157.             for cmd.exe and enter whatever arguments (if any) you had
  9158.  
  9159.  
  9160.  
  9161.  
  9162.                                      Page 141
  9163.  
  9164.      Customizing the Shell
  9165.  
  9166.  
  9167.             been specifying for it on the PROTSHELL or OS2_SHELL line
  9168.             in your config.sys.
  9169.  
  9170.  
  9171.  
  9172.             login.csh
  9173.  
  9174.                login.csh is  read only  by copies  of csh.exe started
  9175.             with the ``-L'' option to make them login or root shells.
  9176.             Typically, this  is a new window.  startup.csh is read by
  9177.             each new  copy of  the shell,  even if  it's invoked as a
  9178.             child of the C shell.
  9179.  
  9180.                The main objective of the login.csh file is to let you
  9181.             set up  those characteristics  that are  inheritable from
  9182.             parent to  child process but which might not be set up if
  9183.             you're starting  from the Start Programs menu (OS/2 1.1),
  9184.             a Group  menu (OS/2  1.2 or  1.3),from the  desktop (OS/2
  9185.             2.x) or  from the  Program  Manager  (Windows  NT).    In
  9186.             addition, it  lets you  do a little special customization
  9187.             of these highest-level shells.
  9188.  
  9189.                The  important  inheritable  characteristics  are  the
  9190.             environmental  variables   together  with   the   current
  9191.             directories and current disk settings.
  9192.  
  9193.  
  9194.  
  9195.  
  9196.  
  9197.  
  9198.  
  9199.  
  9200.  
  9201.  
  9202.  
  9203.  
  9204.  
  9205.  
  9206.  
  9207.  
  9208.  
  9209.  
  9210.  
  9211.  
  9212.  
  9213.  
  9214.  
  9215.  
  9216.  
  9217.  
  9218.  
  9219.  
  9220.  
  9221.  
  9222.  
  9223.  
  9224.                                      Page 142
  9225.  
  9226.                                                         Customizing the Shell
  9227.  
  9228.  
  9229.             The Environmental Variables
  9230.  
  9231.                Most  users   prefer  to  create  the  bulk  of  their
  9232.             environmental variables with SET statements in config.sys
  9233.             under OS/2  or through the Control Panel under Windows NT
  9234.             (to be  inherited by  every process on the system) rather
  9235.             than in  login.csh.   It  means  just  one  copy  of  the
  9236.             definitions in one place, so it's easier to make changes.
  9237.             It also  runs faster since it's all set up when the shell
  9238.             starts; the  shell doesn't  have read all those commands.
  9239.             But if  you're using an initialization script to set some
  9240.             of your  environmentals for  cmd.exe, you'll  want to  do
  9241.             that for the C shell also in login.csh.
  9242.  
  9243.                But there  are cases where it's more convenient to set
  9244.             up some  environmental in  your login.csh.   For example,
  9245.             you might prefer to set your PATH statement there.  Since
  9246.             the C  shell hashes  your search  path, you'll  find it's
  9247.             much faster  finding things even with a very long list of
  9248.             path  directories.    (If  you  actually  had  50  or  so
  9249.             directories, the difference in startup time for something
  9250.             in that  last directory would be around 6 seconds or so!)
  9251.             So you  might find  it more natural to have a much longer
  9252.             PATH with the C shell than with cmd.exe.
  9253.  
  9254.                Also, if  you were  going to  use an  application that
  9255.             needed mixed  case characters  in some of its environment
  9256.             strings and  you were  running on OS/2 1.1, you'd want to
  9257.             define them  in login.csh, not config.sys.   (Using lower
  9258.             case characters in config.sys was unreliable on OS/2 1.1;
  9259.             many users  found it caused random system failures, e.g.,
  9260.             OS/2 crashing while formatting a series of floppies.)
  9261.  
  9262.                In addition  to PATH, the environmental variables used
  9263.             by Hamilton  C shell  include HOME,  PROMPT1 and PROMPT2,
  9264.             TABS, CDPATH, DRIVEMASK, MIXEDCASEDRIVES, SWITCHCHARS and
  9265.             a number of screen color configuration variables.
  9266.  
  9267.                PROMPT1  or  PROMPT2  or  their  aliases  prompt1  and
  9268.             prompt2 control  the prompt  strings you'll see for a new
  9269.             command or a continuation line.
  9270.  
  9271.                TABS is used by more.exe, head.exe, tail.exe and other
  9272.             utilities to  expand out  any tab characters it sees into
  9273.             space characters  on the  screen.    For example, setting
  9274.             TABS = 3 means tabstops every 3 character cells.
  9275.  
  9276.                CDPATH is  used by  cd  and  pushd  to  specify  other
  9277.             directories in addition to the current directory in which
  9278.             to search  for a subdirectory you're trying to change to.
  9279.             Its format  is the  same as  that as  PATH:   a  list  of
  9280.             directories separated  by colons,  but there's no need to
  9281.             list the current directory.
  9282.  
  9283.  
  9284.  
  9285.  
  9286.                                      Page 143
  9287.  
  9288.      Customizing the Shell
  9289.  
  9290.  
  9291.                DRIVEMASK lets  you confine the default list of drives
  9292.             you want  searched when you wildcard a driveletter (e.g.,
  9293.             ``*:\hamilton'') or  reported on  by the  du, pwd and vol
  9294.             utilities.   The value  should be  a list  of  upper-  or
  9295.             lower-case alphabetic  characters or ranges of characters
  9296.             representing  the  drives  you're  interested  in.    For
  9297.             example, setting  DRIVEMASK = cf-h means  you want drives
  9298.             C:, F:, G: and H: reported, assuming they exist.
  9299.  
  9300.                MIXEDCASEDRIVES is  used by  ls.exe,  by  the  shell's
  9301.             fullname and  wildcarding functions  (including  filename
  9302.             completion), by  the  current  directory  functions  (cd,
  9303.             pushd, popd and dirs) and by pwd.exe to tell which drives
  9304.             you want  reported in  the actual  upper  or  lower  case
  9305.             characters returned by the OS/2 kernel.  If you have HPFS
  9306.             or NTFS  drives, it's  possible to  create filenames that
  9307.             have mixed  upper and  lower characters  and you  may not
  9308.             want these  all routinely shifted to lower case.  You set
  9309.             MIXEDCASEDRIVES just  like DRIVEMASK, giving it a list of
  9310.             drives.  It's also possible to list UNC names that should
  9311.             be considered mixed case.  For example, typing
  9312.  
  9313.                  setenv MIXEDCASEDRIVES = [a-z],\\
  9314.  
  9315.             sets all  drive a:  through z:  and all  UNC names on all
  9316.             networked machines as mixed case.  Or for example, typing
  9317.  
  9318.                  setenv MIXEDCASEDRIVES = \\alpha,\\ps2\d^$
  9319.  
  9320.             sets all  the drives on the alpha machine and only the d:
  9321.             drive on ps2 as mixed case.  You can list as many entries
  9322.             in MIXEDCASEDRIVES,  separated by  commas, semicolons  or
  9323.             spaces, as you wish.
  9324.  
  9325.                SWITCHCHARS is used by the shell and all the utilities
  9326.             supplied with  it to  indicate what characters you intend
  9327.             as introducing  one of  the option switches.  By default,
  9328.             the C  shell tries to satisfy users coming from both DOS,
  9329.             OS/2 or  NT and  UNIX backgrounds  and will accept either
  9330.             ``-'' (DOS-style) or ``/'' (UNIX-style) as introducing an
  9331.             option.  Folks coming from a straight UNIX background may
  9332.             find that  inconvenient, particularly  if they're used to
  9333.             typing filenames  using the  forward slash;   ``cd /foo''
  9334.             will certainly  not do  what they want, for example.  The
  9335.             solution is  to ``setenv  SWITCHCHARS = -'', causing only
  9336.             those words that start ``-'' to be recognized as options.
  9337.  
  9338.  
  9339.  
  9340.             Prompt Strings
  9341.  
  9342.                Prompt strings  are  fairly  personal  matter.    This
  9343.             really is  beauty in the eye of the beholder only!  There
  9344.             are two prompt situations:
  9345.  
  9346.  
  9347.  
  9348.                                      Page 144
  9349.  
  9350.                                                         Customizing the Shell
  9351.  
  9352.  
  9353.                1.  The main  prompt, when  the shell  expects  a  new
  9354.                    command.  Set this with PROMPT1.
  9355.  
  9356.                2.  Continuation lines,  where the shell is collecting
  9357.                    more text  before running  something.   An example
  9358.                    would be  whatever  commands  you  type  inside  a
  9359.                    foreach loop.  Set this with PROMPT2.
  9360.  
  9361.                When the  shell needs  to prompt  you, it looks at the
  9362.             appropriate PROMPTx string and evaluates it as if it were
  9363.             looking at  a  double  quoted  string.    Any  backquoted
  9364.             strings or  variable substitutions  it  finds  there  are
  9365.             evaluated and whatever results is printed.  Wildcards are
  9366.             not replaced  nor is  the spacing  affected.   It's quite
  9367.             literally  double-quoted:    the  shell  actually  pastes
  9368.             double quote  characters around the string before passing
  9369.             it to the parser.
  9370.  
  9371.                If you  always wanted  the same  literal  text  string
  9372.             displayed, that  would  be  easy  but  probably  not  too
  9373.             interesting:
  9374.  
  9375.                  543 D% set PROMPT1 = "Hello from CSH!  "
  9376.                  Hello from CSH!  _
  9377.  
  9378.                The  difficult   part  of   setting  your   prompt  is
  9379.             remembering that  if you want a substitution re-evaluated
  9380.             each time  a new prompt is printed, you have to quote the
  9381.             string when  you  define  it  to  defer  the  evaluation.
  9382.             Here's the  wrong, then the right way to create a default
  9383.             IBM-style  prompt  with  your  current  directory  inside
  9384.             rectangular brackets.
  9385.  
  9386.                  Hello from CSH!  set PROMPT1 = "[$upper(cwd)] " #
  9387.                  Wrong way
  9388.                  [D:\DOUG] cdd c:\      # Notice that the prompt
  9389.                  won't change
  9390.                  [D:\DOUG] set PROMPT1 '[$upper(cwd)] ' # Right way
  9391.                  [C:\] _
  9392.  
  9393.                Notice how we're using the built-in upper procedure as
  9394.             if it  were a  variable substitution  with the  ``$''  in
  9395.             front.   When the  shell sees  it's  really  a  procedure
  9396.             reference, what's  inside the parentheses is evaluated as
  9397.             an expression  list.   That's why the cwd variable didn't
  9398.             need its own ``$.''
  9399.  
  9400.                There's really  no limit  to what you can put inside a
  9401.             prompt string.   You  can have  command substitution  and
  9402.             special characters.  It can  even stretch  over  multiple
  9403.             lines if  you put  in carriage  return/newline  character
  9404.             combinations:
  9405.  
  9406.  
  9407.  
  9408.  
  9409.  
  9410.                                      Page 145
  9411.  
  9412.      Customizing the Shell
  9413.  
  9414.  
  9415.                  [C:\] set PROMPT1 = '`date`^r^n$cwd '
  9416.                  Mon Oct 23 1989 11:15:15.03
  9417.                  c:\ _
  9418.  
  9419.                The tradeoff  to  remember  in  creating  your  prompt
  9420.             string is  that whatever you put there is going to be run
  9421.             every time  you need  a new  prompt.   If you make it too
  9422.             complex, it'll  still run,  but it  could  be  annoyingly
  9423.             slow.   Remember that  it takes  longer to  run  external
  9424.             programs than  to use  shell variables or procedures.  If
  9425.             you  want   something  really   unusual,  try  writing  a
  9426.             procedure that  calculates and  returns  the  string  you
  9427.             want.
  9428.  
  9429.  
  9430.  
  9431.             User-Defined Colors
  9432.  
  9433.                All of  the screen  colors used by the C shell and any
  9434.             of the utilities are completely under your control.  Here
  9435.             are the  variables that  control the  color settings  and
  9436.             default values:
  9437.  
  9438.                Name         Use                        Default
  9439.  
  9440.                ADDITIONS    Lines added found by diff. Bright Green
  9441.                COLORS       Normal screen colors.      White on Black
  9442.                DELETIONS    Lines deleted found by diff. Bright Red
  9443.                DIRECTORIES  Directories listed by ls.  Bright
  9444.                DUPLICATES   When filename completion matches  Green
  9445.                             more than one name.
  9446.                FOREIGNFILES Filetypes in a tar file that have no   Br
  9447.                ight Red
  9448.                             counterpart on OS/2 or NT.
  9449.                HIGHLIGHT    Current disk or directory. Bright
  9450.                MATCHFAIL    When filename or command completion    Br
  9451.                ight Red
  9452.                             doesn't match anything.
  9453.                MOREEOF      End or Top of File in more.  Green
  9454.                MOREERROR    Unrecognizable command to more.   Bright
  9455.                Yellow
  9456.                MOREFILLIN   User response to more prompt.     White
  9457.                MOREPROMPT   Prompt line in more.       Green
  9458.                MORETOPMEM   Top of Memory message from more.  Bright
  9459.                Yellow
  9460.                SYSTEMDIRS   Directories with the System bit on.    Br
  9461.                ight Green
  9462.                SYSTEMFILES   Files with the System bit on.    Green
  9463.  
  9464.                You can  choose any  color combinations  you like from
  9465.             the following  set:   black, red,  green,  yellow,  blue,
  9466.             magenta (or blue red), cyan (or blue green) and white.
  9467.  
  9468.  
  9469.  
  9470.  
  9471.  
  9472.                                      Page 146
  9473.  
  9474.                                                         Customizing the Shell
  9475.  
  9476.  
  9477.                Foreground colors  may also  be bright,  dim  (meaning
  9478.             simply, ``not  bright''), blink  or reverse.  The keyword
  9479.             ``on'' introduces  background colors.   Blink only causes
  9480.             true blinking  full-screen; in  a text  window,  it  just
  9481.             makes the  background brighter.   Also,  yellow is a true
  9482.             yellow only if it's bright.  These are system limitations
  9483.             not related to the C shell.
  9484.  
  9485.                The names  of the colors and the keywords bright, dim,
  9486.             blink, reverse  and on  are not case sensitive and may be
  9487.             typed  in   any  combination   of  upper  or  lower  case
  9488.             characters.   The names  of the  environmental  variables
  9489.             themselves must be all in upper case.
  9490.  
  9491.                If  a   foreground  or   background  color   is   left
  9492.             unspecified, that  plane is  considered  transparent  and
  9493.             inherits the color underneath it.
  9494.  
  9495.                You can  set the colors either from within the C shell
  9496.             itself by simply typing the appropriate setenv statements
  9497.             or by  including them  in your login.csh file.  Here's an
  9498.             example color  scheme that's  a little more colorful than
  9499.             the defaults:
  9500.  
  9501.                  setenv  COLORS    =  white on blue
  9502.                  setenv  DELETIONS =  bright white on red
  9503.                  setenv  ADDITIONS =  bright white on green
  9504.                  setenv  MOREPROMPT   =   red on white
  9505.                  setenv  MOREFILLIN   =   black
  9506.                  setenv  MOREERROR =  bright white on red
  9507.  
  9508.                On OS/2, you might also choose to place these settings
  9509.             into your config.sys as the corresponding SET statements:
  9510.  
  9511.                  SET     COLORS=WHITE ON BLUE
  9512.                  SET     DELETIONS=BRIGHT WHITE ON RED
  9513.                  SET     ADDITIONS=BRIGHT WHITE ON GREEN
  9514.                  SET     MOREPROMPT=RED ON WHITE
  9515.                  SET     MOREFILLIN=BLACK
  9516.                  SET     MOREERROR=BRIGHT WHITE ON RED
  9517.  
  9518.             (Notice that  if you  choose to  use  SET  statements  in
  9519.             config.sys, you  should be  sure not  to leave  any space
  9520.             around the equal signs.  Also, unless you're running OS/2
  9521.             1.2 or later, type everything in upper case.)
  9522.  
  9523.                Or, on  Windows  NT,  these  settings  could  be  made
  9524.             through the Control Panel.
  9525.  
  9526.  
  9527.  
  9528.             Initial Current Directories
  9529.  
  9530.  
  9531.  
  9532.  
  9533.  
  9534.                                      Page 147
  9535.  
  9536.      Customizing the Shell
  9537.  
  9538.  
  9539.                The login.csh  file is  also a convenient place to set
  9540.             up all  you  initial  current  directories.    The  Start
  9541.             Programs menu  lets you specify a particular current disk
  9542.             and directory  but not  what your current directories are
  9543.             on the  other  disks  when  you  start  up;  the  current
  9544.             directories  on  those  other  disks  are  always  ``\''.
  9545.             Generally, people find it convenient to be able to choose
  9546.             something  else   and  they   do  this   by  putting  the
  9547.             appropriate ``cd'' statements in login.csh.
  9548.  
  9549.                The final  use for  login.csh is in setting up certain
  9550.             local variables  that you  want different  in  the  login
  9551.             shell.   For example,  a login  shell  normally  dumps  a
  9552.             history list when it exits; you may want to turn this off
  9553.             by setting  savehist = 0.  Also, you may not want an end-
  9554.             of-file (from accidentally hitting ^Z once to many times)
  9555.             to cause  the shell to exit; you can tell to insist on an
  9556.             exit statement by setting ignoreeof = 1.
  9557.  
  9558.  
  9559.  
  9560.             startup.csh
  9561.  
  9562.                The startup.csh  file is  read by  all copies of the C
  9563.             shell, not just login or root level copies.  If you don't
  9564.             want the startup file read, you have to specifically tell
  9565.             it with  the ``-F'' (Faster startup) option.  startup.csh
  9566.             is read  after login.csh  whenever both  are being  read.
  9567.             This means  you can depend on the environmental variables
  9568.             being set up already when the startup file runs.
  9569.  
  9570.                startup.csh is  a good  place to define any aliases or
  9571.             function key  definitions you  use, since  you'd probably
  9572.             always want  them available  but can't  pass them  in the
  9573.             environment  to   any  child  copies  of  csh.exe.    The
  9574.             startup.csh file  that comes  with the  shell  defines  a
  9575.             number of  popular aliases  including some for getting at
  9576.             some of  cmd.exe's internal  functions; most people add a
  9577.             few of their own.
  9578.  
  9579.                The  other   thing  you   may  want  to  add  to  your
  9580.             startup.csh  file  are  settings  for  some  of  the  set
  9581.             variables that  customize how  the  shell  runs.    These
  9582.             aren't passed in the environment.  Look through the lists
  9583.             in the  Language Reference section.  Some you may want to
  9584.             set differently than the defaults are bsdhistory, cdhome,
  9585.             chgdisk,     escapesym,      histchars,     ignoreerrors,
  9586.             ignorestatus,   noclobber,   nonomatch,   nullwords   and
  9587.             tailstatus.   A lot  of what  you choose  will depend  on
  9588.             whether you're coming from a DOS or a UNIX background.
  9589.  
  9590.  
  9591.  
  9592.             Change Directory
  9593.  
  9594.  
  9595.  
  9596.                                      Page 148
  9597.  
  9598.                                                         Customizing the Shell
  9599.  
  9600.  
  9601.                If your  background is DOS, you'll probably want cd to
  9602.             just report the current directory if you don't give it an
  9603.             argument.   Those with  a UNIX  background may want it to
  9604.             mean ``change  to the  home disk and directory.''  That's
  9605.             determined with  the cdhome  variable; the  default is  a
  9606.             DOS-style reporting only.
  9607.  
  9608.                Another customization you may to do is to intercept cd
  9609.             so that  you can  capture  your  last  current  directory
  9610.             whenever you change directories:
  9611.  
  9612.                  proc cd(dest)
  9613.                     @ lwd = cwd    # capture the last working
  9614.                  directory
  9615.                     if ($dest == "")
  9616.                        chdir
  9617.                     else
  9618.                        chdir $dest
  9619.                     end
  9620.                  end
  9621.  
  9622.  
  9623.  
  9624.             Berkeley-style History and Escapes
  9625.  
  9626.                Also, if your fingers learned to use the ``!-n'' style
  9627.             of history  references on  a Berkeley UNIX system, you'll
  9628.             want to  set  bsdhistory = 1.  True die-hard (and perhaps
  9629.             daring) former  UNIX  users  may  want  try  setting  the
  9630.             escapesym back  to a  backslash; it'll  work with  the  C
  9631.             shell but  you're on  your own with other applications or
  9632.             tools.
  9633.  
  9634.  
  9635.  
  9636.             Berkeley Compatibility Mode
  9637.  
  9638.                Hamilton C  shell does  implement a substantial number
  9639.             of  significant   improvements  over  the  over  original
  9640.             Berkeley C  shell.  By and large, we expect most users to
  9641.             find these  changes welcome.  But if you're trying to run
  9642.             a script  developed using  the Berkeley C shell or if you
  9643.             simply  want   get  a   more  precise  ``Berkeley  mode''
  9644.             interactively, you can do that.
  9645.  
  9646.                Following a  common convention  on UNIX that the first
  9647.             line of  a script  can identify the language processor to
  9648.             be used  with it, if the C shell encounters a script that
  9649.             starts with
  9650.  
  9651.                  #!/bin/csh
  9652.  
  9653.             it will  shift to  a  fairly  precise  emulation  of  the
  9654.             original Berkeley C shell.
  9655.  
  9656.  
  9657.  
  9658.                                      Page 149
  9659.  
  9660.      Customizing the Shell
  9661.  
  9662.  
  9663.                To enter  this mode  for interactive work, start the C
  9664.             shell with the ``-B'' (Berkeley compatibility) option.
  9665.  
  9666.                For more  details on  differences between the Hamilton
  9667.             and Berkeley C shells and on Berkeley compatibility mode,
  9668.             please  please   refer  to   the  Compatibility   section
  9669.             beginning on page 162.
  9670.  
  9671.  
  9672.  
  9673.             Error Handling
  9674.  
  9675.                ignoreerrors, ignorestatus,  noclobber, nonomatch  and
  9676.             nullwords let  you  tailer  how  the  shell  responds  to
  9677.             various exception  situations.   They let  you  determine
  9678.             whether  you  think  certain  things  are  errors.    For
  9679.             example, should  a child  process that returns a non-zero
  9680.             return code but otherwise seems to run okay be considered
  9681.             an error?   If  you set  ignorestatus =  0, it  will  be.
  9682.             Similarly,  noclobber   lets  you   intercept  accidental
  9683.             attempts  to   overwrite  an   existing  file   with  i/o
  9684.             redirection.   nonomatch  tells  what  should  happen  if
  9685.             wildcarding doesn't  match  anything.    nullwords  tells
  9686.             whether you think it's an error to use a subscript that's
  9687.             off the end of an array.
  9688.  
  9689.  
  9690.  
  9691.             Calling the C shell from Other Applications
  9692.  
  9693.                Many applications,  e.g., editors,  make utilities and
  9694.             so on,  depend on  being able  to  call  up  the  command
  9695.             processor.   For example,  make uses  cmd.exe to actually
  9696.             process each  command in the make file that it determines
  9697.             should  be   run.     Most  editors   (and   many   other
  9698.             applications) provide  a way  of  temporarily  suspending
  9699.             themselves and  invoking cmd.exe  so you  can run  a  few
  9700.             commands and then exit to return back to the editor.
  9701.  
  9702.                Usually,  these   applications  look  at  the  COMSPEC
  9703.             environmental variable to determine the full pathname for
  9704.             cmd.exe.   If, like  make, they're just calling it with a
  9705.             single command on the command line, they use cmd.exe's /C
  9706.             option.
  9707.  
  9708.                If you'd  like to  use the  C shell instead of cmd.exe
  9709.             with these  applications, set  COMSPEC to  point to the C
  9710.             shell  instead   and  use  the  CSHOPTIONS  environmental
  9711.             variable to  tell the  C shell to interpret the /C option
  9712.             flag in  a way that's compatible with the meaning cmd.exe
  9713.             would attach to it:
  9714.  
  9715.                  setenv COMSPEC = c:\hamilton\bin\csh.exe
  9716.                  setenv CSHOPTIONS = -X
  9717.  
  9718.  
  9719.  
  9720.                                      Page 150
  9721.  
  9722.                                                         Customizing the Shell
  9723.  
  9724.  
  9725.                Alternately, you  can put these definitions right into
  9726.             your config.sys, rewriting them as:
  9727.  
  9728.                  set COMSPEC=c:\hamilton\bin\csh.exe
  9729.                  set CSHOPTIONS=-X
  9730.  
  9731.                When the  C shell  starts up,  if  it  discovers  that
  9732.             COMSPEC points to itself, it will look through the search
  9733.             path to  find the  real cmd.exe.  This is to make sure it
  9734.             will still  be able  to run  .cmd files.   Since  the  -X
  9735.             option is  a toggling  option, you  can still  get at the
  9736.             original meaning of the -C option by typing -XC to toggle
  9737.             back.
  9738.  
  9739.  
  9740.  
  9741.  
  9742.  
  9743.  
  9744.  
  9745.  
  9746.  
  9747.  
  9748.  
  9749.  
  9750.  
  9751.  
  9752.  
  9753.  
  9754.  
  9755.  
  9756.  
  9757.  
  9758.  
  9759.  
  9760.  
  9761.  
  9762.  
  9763.  
  9764.  
  9765.  
  9766.  
  9767.  
  9768.  
  9769.  
  9770.  
  9771.  
  9772.  
  9773.  
  9774.  
  9775.  
  9776.  
  9777.  
  9778.  
  9779.  
  9780.  
  9781.  
  9782.                                      Page 151
  9783.  
  9784.      Customizing the Shell
  9785.  
  9786.  
  9787.  
  9788.                                         
  9789.  
  9790.  
  9791.  
  9792.  
  9793.  
  9794.  
  9795.  
  9796.  
  9797.  
  9798.  
  9799.  
  9800.  
  9801.  
  9802.  
  9803.  
  9804.  
  9805.  
  9806.  
  9807.  
  9808.  
  9809.  
  9810.  
  9811.  
  9812.  
  9813.  
  9814.  
  9815.  
  9816.  
  9817.  
  9818.  
  9819.  
  9820.  
  9821.  
  9822.  
  9823.  
  9824.  
  9825.  
  9826.  
  9827.  
  9828.  
  9829.  
  9830.  
  9831.  
  9832.  
  9833.  
  9834.  
  9835.  
  9836.  
  9837.  
  9838.  
  9839.  
  9840.  
  9841.  
  9842.  
  9843.  
  9844.                                      Page 152
  9845.  
  9846.                                                                       Summary
  9847.  
  9848.  
  9849.  
  9850.                                         
  9851.  
  9852.  
  9853.  
  9854.  
  9855.                                      Summary
  9856.  
  9857.  
  9858.                The next  few pages  show a  couple of  somewhat  more
  9859.             full-blown examples  and  outline  the  contents  of  the
  9860.             samples directory.   There's  also detailed discussion of
  9861.             the  compatibility   issues  between   the  Hamilton  and
  9862.             original Berkeley C shells.
  9863.  
  9864.                Try some  experiments.    We  hope  you'll  find  this
  9865.             product powerful,  fast, reliable  and easy  to use.   We
  9866.             hope it  will help  you get  your work  done  faster  and
  9867.             perhaps, more pleasantly.
  9868.  
  9869.  
  9870.  
  9871.  
  9872.  
  9873.  
  9874.  
  9875.  
  9876.  
  9877.  
  9878.  
  9879.  
  9880.  
  9881.  
  9882.  
  9883.  
  9884.  
  9885.  
  9886.  
  9887.  
  9888.  
  9889.  
  9890.  
  9891.  
  9892.  
  9893.  
  9894.  
  9895.  
  9896.  
  9897.  
  9898.  
  9899.  
  9900.  
  9901.  
  9902.  
  9903.  
  9904.  
  9905.  
  9906.                                      Page 153
  9907.  
  9908.      Summary
  9909.  
  9910.  
  9911.                                         
  9912.  
  9913.  
  9914.  
  9915.  
  9916.  
  9917.  
  9918.  
  9919.  
  9920.  
  9921.  
  9922.  
  9923.  
  9924.  
  9925.  
  9926.  
  9927.  
  9928.  
  9929.  
  9930.  
  9931.  
  9932.  
  9933.  
  9934.  
  9935.  
  9936.  
  9937.  
  9938.  
  9939.  
  9940.  
  9941.  
  9942.  
  9943.  
  9944.  
  9945.  
  9946.  
  9947.  
  9948.  
  9949.  
  9950.  
  9951.  
  9952.  
  9953.  
  9954.  
  9955.  
  9956.  
  9957.  
  9958.  
  9959.  
  9960.  
  9961.  
  9962.  
  9963.  
  9964.  
  9965.  
  9966.  
  9967.  
  9968.                                      Page 154
  9969.  
  9970.                                                                      Examples
  9971.  
  9972.  
  9973.             
  9974.  
  9975.  
  9976.                                     Examples
  9977.  
  9978.  
  9979.             Factor.csh:  A self-loading procedure which prints a list
  9980.             of the  factors of  a number,  illustrating  the  use  of
  9981.             recursion.
  9982.  
  9983.                 
  9984.                 proc factor(n)
  9985.                   if (n > 2) then
  9986.                      for i = 2 to floor(sqrt(n)) do
  9987.                         if (n % i == 0) then
  9988.                            echo $i
  9989.                             return factor(n/i)
  9990.                         end
  9991.                      end
  9992.                   end
  9993.                   return n
  9994.                 end
  9995.                 
  9996.                 factor $argv
  9997.  
  9998.             Invoked as:
  9999.  
  10000.                 factor 6324489
  10001.  
  10002.             It would print:
  10003.  
  10004.                 3
  10005.                 3
  10006.                 702721
  10007.  
  10008.             To print  the factors  on one  line and  time how long it
  10009.             takes:
  10010.  
  10011.                 time echo `factor 6324489`
  10012.  
  10013.             The `...`  sequence  means  command  substitution:    run
  10014.             what's inside  the backquotes  and substitute  the output
  10015.             back onto the command line.  This would print:
  10016.  
  10017.                 3 3 702721
  10018.                 0:00:02.35
  10019.  
  10020.  
  10021.  
  10022.  
  10023.  
  10024.  
  10025.  
  10026.  
  10027.  
  10028.  
  10029.  
  10030.                                      Page 155
  10031.  
  10032.      Examples
  10033.  
  10034.  
  10035.             
  10036.             
  10037.             Whereis.csh:   A self-loading  procedure to  find all the
  10038.             files anywhere  on the  search path  corresponding to the
  10039.             command name,  illustrating  pattern  matching  and  file
  10040.             system tests.
  10041.  
  10042.                 
  10043.                 proc whereis(name)
  10044.                   local i, j
  10045.                   if (name =~ "*.*") then
  10046.                      foreach i ($path)
  10047.                         if (i =~ "*\") then
  10048.                            if (-e $i$name) echo $i$name
  10049.                         else
  10050.                            if (-e $i\$name) echo $i\$name
  10051.                         end
  10052.                      end
  10053.                   else
  10054.                      foreach i ($path)
  10055.                         if (i =~ "*\") then
  10056.                            foreach j (.csh .exe .com .cmd)
  10057.                               if (-e $i$name$j) echo $i$name$j
  10058.                            end
  10059.                         else
  10060.                            foreach j (.csh .exe .com .cmd)
  10061.                               if (-e $i\$name$j) echo $i\$name$j
  10062.                            end
  10063.                         end
  10064.                      end
  10065.                   end
  10066.                 end
  10067.                 
  10068.                 whereis $argv
  10069.  
  10070.             Invoked as:
  10071.  
  10072.                 whereis ls
  10073.  
  10074.             It would print:
  10075.  
  10076.                 c:\os2\bin\ls.exe
  10077.  
  10078.             ls.exe is the file directory lister.  Invoked as:
  10079.  
  10080.                 time ls -l `whereis more`
  10081.  
  10082.             It would  show the  two versions of more.  (Our more ``is
  10083.             less filling and tastes better.'')
  10084.  
  10085.                 ---A-  Mar 20  8:00   20123  c:\os2\hamilton\more.exe
  10086.                 ---A-  Oct 26 12:00   31658  c:\os2\ibm\more.com
  10087.                 0:00:00.97
  10088.  
  10089.  
  10090.  
  10091.  
  10092.                                      Page 156
  10093.  
  10094.                                                                      Examples
  10095.  
  10096.  
  10097.             
  10098.  
  10099.  
  10100.                                 Samples Directory
  10101.  
  10102.  
  10103.                The sample  C programs  and C  shell  scripts  in  the
  10104.             samples directory  are  meant  to  help  you  install  or
  10105.             experiment with  Hamilton C shell.  Deliberately, they're
  10106.             relatively trivial.  All were created assuming TABS=3.
  10107.  
  10108.             args.c         A simple  C program  that prints  out  the
  10109.                            *argv[]     (argument)     and     *envp[]
  10110.                            (environmental variable)  arrays.   Notice
  10111.                            that wildcarding,  variable substitutions,
  10112.                            quoting and command substitutions are done
  10113.                            before the  C program  is started.  If you
  10114.                            do a  lot of  wildcarding, you  can create
  10115.                            and pass VERY long parameter lists (up 64K
  10116.                            characters.)  Try some of these commands:
  10117.  
  10118.                                 % args "ho"w 'no'w
  10119.                                 % args "$cwd" '$cwd'
  10120.                                 % args * "*" '*'
  10121.                                 % args `whereis more`
  10122.                                 % args '`whereis more`'
  10123.                                 % args * *\* *\*\* | more
  10124.  
  10125.             bits.csh       A  simple   self-loading  procedure   that
  10126.                            calculates the  minimum bits  required  to
  10127.                            represent the  argument it's  passed as  a
  10128.                            binary integer.
  10129.  
  10130.             bumpdate.csh   Print the date n number of days forward or
  10131.                            backward from  a given  date.  If only the
  10132.                            bump  value  is  given,  today's  date  is
  10133.                            bumped.
  10134.  
  10135.             caldate.csh    Print the  date corresponding  to a  given
  10136.                            Julian day.
  10137.  
  10138.             calendar.csh   A C  shell script  for  printing  out  the
  10139.                            calendar for any given month, highlighting
  10140.                            the current  date.   If no  date is given,
  10141.                            this month's calendar is printed.
  10142.  
  10143.             colors.csh     Instructions and  examples on  customizing
  10144.                            the screen colors.
  10145.  
  10146.             cl.csh         On NT  only, run  the compiler  and linker
  10147.                            for an  NT program.  Avoids having to fool
  10148.                            with a  make file  just to  compile hello,
  10149.                            world.  Works pretty much just like the cl
  10150.                            command on DOS would.
  10151.  
  10152.  
  10153.  
  10154.                                      Page 157
  10155.  
  10156.      Examples
  10157.  
  10158.  
  10159.             deltaday.csh   Print the  number of  days separating  two
  10160.                            dates.   If only  one date  is given,  the
  10161.                            difference between  it and today's date is
  10162.                            returned.
  10163.  
  10164.             dumpenv.c      This C  program writes out the environment
  10165.                            it's  passed   in  the   form  of   setenv
  10166.                            commands.  If you're installing Hamilton C
  10167.                            shell for  the first  time, dumpenv  is  a
  10168.                            convenient    way    to    snapshot    the
  10169.                            environmental variables  you've been using
  10170.                            with cmd.exe  in a  form you can append to
  10171.                            your login.csh file.
  10172.  
  10173.             duplicat.csh   Look for  duplicate files  anywhere  in  a
  10174.                            directory tree.
  10175.  
  10176.             easter.csh     A C  shell  script  that  calculates  when
  10177.                            Easter will  occur in  any given year.  If
  10178.                            no year  is given,  the  current  year  is
  10179.                            assumed.
  10180.  
  10181.             factor.csh     The simple  factor C shell script shown in
  10182.                            the User  Guide.  It's intended to show to
  10183.                            show the  use of  recursion,  expressions,
  10184.                            and a self-loading procedure.
  10185.  
  10186.             finance.csh    Another C  shell script showing expression
  10187.                            evaluation.   This  defines  a  number  of
  10188.                            routines   for    calculating    financial
  10189.                            conversion factors,  e.g., from present to
  10190.                            future value.
  10191.  
  10192.             getprio.c      This C  program (supplied  with  the  OS/2
  10193.                            version)   retrieves    and   prints   its
  10194.                            scheduling  priority,   demonstrating  the
  10195.                            effect of  using the eval command to run a
  10196.                            command at  a higher  or  lower  priority.
  10197.                            Try these examples:
  10198.  
  10199.                                 % getprio
  10200.                                 % eval -i getprio
  10201.                                 % eval +20 (getprio; eval +20
  10202.                                 getprio; getprio); getprio
  10203.  
  10204.             julian.csh     Calculate the Julian day number (number of
  10205.                            days since  January 1,  4713 B.C.) for any
  10206.                            given date.   If you don't give a date, it
  10207.                            uses today's date.
  10208.  
  10209.             makecpgm.csh   A simple C shell script (supplied with the
  10210.                            OS/2  version)   showing  how  a  ``make''
  10211.                            function might  be written  in the C shell
  10212.                            language.   This  one  rebuilds  any  .exe
  10213.  
  10214.  
  10215.  
  10216.                                      Page 158
  10217.  
  10218.                                                                      Examples
  10219.  
  10220.  
  10221.                            files in  the current  directory that  are
  10222.                            older than  the corresponding  .c file  or
  10223.                            any of  the .h files.  In fact, the .exe's
  10224.                            in this  directory were  built  with  this
  10225.                            script.
  10226.  
  10227.             mcvisa.csh     A simple  C shell script that constructs a
  10228.                            special checksum  of a  credit card number
  10229.                            to tell if the card number is plausible or
  10230.                            not.   The checksum  used is  designed  to
  10231.                            catch transposed or incorrect digits.  Try
  10232.                            it on the cards in your wallet.
  10233.  
  10234.             myecho.c       A variation  on the  built-in echo command
  10235.                            that prints  its *argv[]  (argument)  list
  10236.                            with quotes  around each  word it's passed
  10237.                            and tells  the total character count.  Try
  10238.                            these examples:
  10239.  
  10240.                                 % myecho now     is the
  10241.                                 % myecho "now     is" the
  10242.                                 % myecho `ls`
  10243.                                 % myecho `echo`
  10244.                                 % myecho `echo hello`
  10245.                                 % myecho * *\* *\*\* | more
  10246.  
  10247.             newfiles.csh   List all  the files  or directories in the
  10248.                            current directory that do not occur in the
  10249.                            specified directory.
  10250.  
  10251.             postage.csh    Calculate the  U.S.  first  class  postage
  10252.                            required for a given weight in ounces.
  10253.  
  10254.             rcode.c        A trivial C program that just prints, then
  10255.                            exits with  the return code value you pass
  10256.                            it.   You can  use this routine to see how
  10257.                            the status  variable is  set and also, how
  10258.                            the ``;,''  ``||''  and  ``&&''  statement
  10259.                            connectors work.  Try these examples:
  10260.  
  10261.                                 % rcode
  10262.                                 % calc status
  10263.                                 % rcode 1
  10264.                                 % calc status
  10265.                                 % echo $status
  10266.                                 % echo status
  10267.                                 % rcode 2
  10268.                                 % calc status
  10269.                                 % rcode 0 || rcode 1
  10270.                                 % rcode 1 || rcode 2
  10271.                                 % rcode 0 && rcode 1
  10272.                                 % rcode 1 && rcode 2
  10273.                                 % rcode 0 ;  rcode 1
  10274.                                 % rcode 1 ;  rcode 2
  10275.  
  10276.  
  10277.  
  10278.                                      Page 159
  10279.  
  10280.      Examples
  10281.  
  10282.  
  10283.                            rcode also  illustrates another  aspect of
  10284.                            return codes  to consider:   if  you use C
  10285.                            library stdio  (as rcode.c  does) and  you
  10286.                            exit with  a non-zero  return code,  stdio
  10287.                            thinks  it   was  an  error  and  discards
  10288.                            anything in  the stdio  buffers.   In  the
  10289.                            following example,  stdio  writes  to  the
  10290.                            screen are  unbuffered so  it  works;  but
  10291.                            pipes  are   buffered,  so   nothing  gets
  10292.                            written to it:
  10293.  
  10294.                                 % rcode 1
  10295.                                 1
  10296.                                 % rcode 1 | more
  10297.                                 --- End of file ---
  10298.                                 %
  10299.  
  10300.                            If you're writing an application that uses
  10301.                            return  codes,   you  should  remember  to
  10302.                            explicitly flush  the buffers  with  stdio
  10303.                            fflush() or use the kernel routines, e.g.,
  10304.                            DosWrite(), directly
  10305.  
  10306.             sizeof.csh     A short C shell script that calculates and
  10307.                            prints the  cumulative size  of any number
  10308.                            of files or directories.
  10309.  
  10310.             ts.csh         A  C   shell  script   that  searches  for
  10311.                            occurrences of  a simple string in all the
  10312.                            files with a given extension anywhere in a
  10313.                            directory tree.
  10314.  
  10315.             viopaste.c     A short  C program (supplied with the OS/2
  10316.                            version)  to   enable   pasting   into   a
  10317.                            Presentation  Manager  text  window  under
  10318.                            OS/2 1.2 or 1.3.
  10319.  
  10320.             weekday.csh    Print the day of the week corresponding to
  10321.                            any given date.
  10322.  
  10323.             winerror.csh   Print the Win32 message corresponding to a
  10324.                            given error code.  (Only supplied with the
  10325.                            Windows NT version.)
  10326.  
  10327.  
  10328.  
  10329.  
  10330.  
  10331.  
  10332.  
  10333.  
  10334.  
  10335.  
  10336.  
  10337.  
  10338.  
  10339.  
  10340.                                      Page 160
  10341.  
  10342.                                                                      Examples
  10343.  
  10344.  
  10345.  
  10346.                                         
  10347.  
  10348.  
  10349.  
  10350.  
  10351.  
  10352.  
  10353.  
  10354.  
  10355.  
  10356.  
  10357.  
  10358.  
  10359.  
  10360.  
  10361.  
  10362.  
  10363.  
  10364.  
  10365.  
  10366.  
  10367.  
  10368.  
  10369.  
  10370.  
  10371.  
  10372.  
  10373.  
  10374.  
  10375.  
  10376.  
  10377.  
  10378.  
  10379.  
  10380.  
  10381.  
  10382.  
  10383.  
  10384.  
  10385.  
  10386.  
  10387.  
  10388.  
  10389.  
  10390.  
  10391.  
  10392.  
  10393.  
  10394.  
  10395.  
  10396.  
  10397.  
  10398.  
  10399.  
  10400.  
  10401.  
  10402.                                      Page 161
  10403.  
  10404.      Compatibility
  10405.  
  10406.  
  10407.             
  10408.  
  10409.  
  10410.                                Compatibility Guide
  10411.  
  10412.  
  10413.             This section details the specific differences between the
  10414.             Hamilton C shell and the original UNIX C shell+.  It also
  10415.             describes the  Hamilton C  shell's Berkeley compatibility
  10416.             mode, used for running Berkeley C shell scripts.
  10417.  
  10418.  
  10419.  
  10420.             Berkeley 4.3 Buglist problems have been fixed.
  10421.  
  10422.             1.   Shell procedures  have been  provided and the clumsy
  10423.                  argument mechanism for aliases has been dropped.
  10424.  
  10425.             2.   Commands  typed   within  loops   or  other  control
  10426.                  structures are properly added to the history list.
  10427.  
  10428.             3.   Control structures  are recursively parsed, allowing
  10429.                  piping between them.  For example:
  10430.  
  10431.                       foreach i (a b c) echo $a; end | wc
  10432.  
  10433.                  properly displays
  10434.  
  10435.                               3        3       12
  10436.  
  10437.             4.   Any of  the `:' editing modifiers can be used on any
  10438.                  substitution.   Also,  a  space  inside  the  search
  10439.                  string in  a ``:s/.../.../''  command will match the
  10440.                  space between  two words.  In the UNIX C shell, only
  10441.                  certain modifiers  could be  used on a given type of
  10442.                  substitution and  it is  not possible  to perform  a
  10443.                  search/replace that crossed word boundaries.
  10444.  
  10445.  
  10446.  
  10447.             The language has been regularized.
  10448.  
  10449.             1.   The set,  setenv and  alias commands will now accept
  10450.                  the same  basic syntax.   The  UNIX C  shell  had  a
  10451.                  number of anomalies:  an `=' sign was required for a
  10452.                  set but  not for  setenv and alias; parenthesis were
  10453.                  required around  a word  list for  a set but not for
  10454.                  setenv and  alias; the set statement ignored all but
  10455.                  the first argument word but alias would not, etc.
  10456.             ____________________
  10457.             + The references used for comparison are the Berkeley 4.3
  10458.               Unix User's  Manual:   Reference Guide  (University  of
  10459.               California, 1986)  and The  UNIX C Shell Field Guide by
  10460.               Gail and Paul Anderson (Prentice-Hall, 1986.)
  10461.  
  10462.  
  10463.  
  10464.                                      Page 162
  10465.  
  10466.                                                                 Compatibility
  10467.  
  10468.  
  10469.             2.   Variables or  word lists are always indexed counting
  10470.                  the first  word as  element zero.   The UNIX C shell
  10471.                  counted from zero when indexing with ``:n'' notation
  10472.                  but from  one when  using ``[n]'' notation.  argv[0]
  10473.                  is the  first argument  word, not  the name  of  the
  10474.                  shell script being executed.  The name of the script
  10475.                  is kept in the local variable $scriptname.  This can
  10476.                  be overridden  by setting the inheritable per-thread
  10477.                  variable bsdargv = 1, causing argv[0] to be the name
  10478.                  of the script.
  10479.  
  10480.             3.   In keeping  with the  desire to  consistently  index
  10481.                  from zero, the last command entered into the history
  10482.                  list, ``!!'',  is considered  the 0-th element; ``!-
  10483.                  1'' is  the line  before  it.    The  UNIX  C  shell
  10484.                  considered  these  to  be  the  same.    A  built-in
  10485.                  variable, bsdhistory,  is provided  for those  whose
  10486.                  fingers prefer  the Berkeley  numbering  convention:
  10487.                  if you  set bsdhistory  = 1,  ``!!'' and ``!-1'' are
  10488.                  the same.
  10489.  
  10490.             4.   Where an  expression is  expected, conventional high
  10491.                  level language syntax is now acceptable.  The UNIX C
  10492.                  shell  required   spaces   around   any   expression
  10493.                  operators, a  variable reference  required a  `$' to
  10494.                  introduce it,  parenthesis were  required  to  avoid
  10495.                  confusing ``less  than'' with  i/o redirection, etc.
  10496.                  What had to be typed as
  10497.  
  10498.                       @ i = ($j + 3 * $k < 10)
  10499.  
  10500.                  under the  UNIX  C  shell  can  now  be  typed  (for
  10501.                  example) as
  10502.  
  10503.                       @ i=j+3*k<10
  10504.  
  10505.                  (The original  UNIX C  shell  expression  syntax  is
  10506.                  still entirely  acceptable and  will  still  produce
  10507.                  correct results.)
  10508.  
  10509.             5.   Inside a  ``[...]'' array  index, the  shell  always
  10510.                  looks for an expression, never an editing-style word
  10511.                  select.   Syntax and  keying rules  are the  same as
  10512.                  with any expression.
  10513.  
  10514.             6.   The case  statement now  accepts an expression to be
  10515.                  matched rather  than only  a pattern.  (To specify a
  10516.                  static pattern, enclose it in quotes.)  To determine
  10517.                  a match  against a  case clause, the case expression
  10518.                  is evaluated, converted to a string and then used as
  10519.                  a pattern to compare against the switch value.
  10520.  
  10521.             7.   The various  different end  statements used  by  the
  10522.                  UNIX C  shell,  end,  endif  and  endsw,  have  been
  10523.  
  10524.  
  10525.  
  10526.                                      Page 163
  10527.  
  10528.      Compatibility
  10529.  
  10530.  
  10531.                  replaced by  a single end statement.  Similarly, the
  10532.                  two break  statements, break  and breaksw, have been
  10533.                  replaced  with   a  single  break  statement.    For
  10534.                  compatibility with  existing scripts,  the  obsolete
  10535.                  keywords are implemented as aliases.
  10536.  
  10537.             8.   Since Hamilton  C shell  is free  format (i.e.,  new
  10538.                  statements need not begin on a new line), the UNIX C
  10539.                  shell convention  of chaining  if statements  with a
  10540.                  single end  if the  else and if are on the same line
  10541.                  isn't possible.   Instead,  an elif keyword has been
  10542.                  added.
  10543.  
  10544.             9.   The obscure use of several break statements in a row
  10545.                  on a  single line  to break out of several levels of
  10546.                  control statements  at once has been eliminated.  In
  10547.                  its place, a label may be specified as an operand to
  10548.                  indicate the control structure to ``break'' out of.
  10549.  
  10550.  
  10551.  
  10552.  
  10553.  
  10554.  
  10555.  
  10556.  
  10557.  
  10558.  
  10559.  
  10560.  
  10561.  
  10562.  
  10563.  
  10564.  
  10565.  
  10566.  
  10567.  
  10568.  
  10569.  
  10570.  
  10571.  
  10572.  
  10573.  
  10574.  
  10575.  
  10576.  
  10577.  
  10578.  
  10579.  
  10580.  
  10581.  
  10582.  
  10583.  
  10584.  
  10585.  
  10586.  
  10587.  
  10588.                                      Page 164
  10589.  
  10590.                                                                 Compatibility
  10591.  
  10592.  
  10593.             Modern compiler technology has been employed.
  10594.  
  10595.                  Statements are  parsed and compiled into an internal
  10596.             form before  any substitutions  or  other  evaluation  is
  10597.             attempted.     This  offers   an   enormous   performance
  10598.             improvement, particularly  when  iteration  is  involved.
  10599.             (The UNIX  C shell  would actually reparse each statement
  10600.             inside a foreach loop each time through the loop.)
  10601.  
  10602.                  If command-  or variable-substitution creates any of
  10603.             the following  reserved  words  or  tokens,  the  special
  10604.             semantic meaning  will be lost since substitution is done
  10605.             after parsing of statement structure.  Instead, they will
  10606.             simply be  treated as  character strings.  These reserved
  10607.             words are:
  10608.  
  10609.               Introducing a clause in a structured statement:
  10610.  
  10611.                  alias     elif      if        setkey    unproc
  10612.                  break     else      local     source    unset
  10613.                  by        end       onintr    switch    unsetenv
  10614.                  calc      eval      proc      then      unsetkey
  10615.                  case      exit      repeat    time      until
  10616.                  continue  for       return    to        while
  10617.                  default   foreach   set       unalias   @
  10618.                  do        goto      setenv    unlocal
  10619.  
  10620.               Anywhere:
  10621.  
  10622.                            ( ) < > & | ;
  10623.  
  10624.               In an expression:
  10625.  
  10626.                            + - * / % =
  10627.  
  10628.                  Similarly, labels  cannot be  run-time evaluated  to
  10629.             see what  the  label  on  a  statement  is;  it  must  be
  10630.             evaluated when the statement is first parsed.
  10631.  
  10632.  
  10633.  
  10634.             Extensions:
  10635.  
  10636.             1.   Command line  editing with the arrow keys, etc., and
  10637.                  the setkey statements are new.
  10638.  
  10639.             2.   The procedure  mechanism, including the proc, unproc
  10640.                  and   return statements  and  the  various  built-in
  10641.                  procedures, is new.
  10642.  
  10643.             3.   Local variables and local and unlocal statements are
  10644.                  new.
  10645.  
  10646.  
  10647.  
  10648.  
  10649.  
  10650.                                      Page 165
  10651.  
  10652.      Compatibility
  10653.  
  10654.  
  10655.             4.   The use  of color highlighting to indicate exception
  10656.                  situations in filename or command completion is new.
  10657.  
  10658.             5.   The for  statement, providing numeric iteration, and
  10659.                  the calc  statement,  which  writes  the  result  of
  10660.                  expression evaluation to stdout, are new.
  10661.  
  10662.             6.   The ``**''  and ``**='' exponentiation operators are
  10663.                  new.
  10664.  
  10665.             7.   Floating point arithmetic is new.
  10666.  
  10667.             8.   The path  hashing mechanism  is  substantially  less
  10668.                  sensitive to  blindspots caused  by creating  a  new
  10669.                  executable in  one of  the path  directories and not
  10670.                  manually specifying  rehash.  The UNIX C shell would
  10671.                  not be able to find the new file; this shell makes a
  10672.                  second pass  through the  path directories  whenever
  10673.                  hashing fails,  looking for  this  sort  of  problem
  10674.                  before it reports failure.  If it finds a blindspot,
  10675.                  it automatically rehashes that directory.
  10676.  
  10677.             9.   History references  are allowed  in the  inline text
  10678.                  supplied with  the ``<<'' i/o redirection mechanism.
  10679.                  Also, the  inline text  is remembered in the history
  10680.                  list, each  line as  a single  word. This avoids the
  10681.                  user having  to remember  and retype the inline text
  10682.                  any time  one of  these statements  is recalled from
  10683.                  the history  list or  if the  history list is dumped
  10684.                  for use in a script file.
  10685.  
  10686.             10.  Exclusion ranges, e.g., ``[^a-z],'' can be used in a
  10687.                  wildcard pattern.
  10688.  
  10689.             11.  Escape sequences to encode special characters (e.g.,
  10690.                  ``^a'' for audible bell or ``^b'' for backspace) are
  10691.                  recognized in the arguments to any command, not just
  10692.                  echo.   Because this  processing is  internal to the
  10693.                  shell, it  is not necessary to type two escapes in a
  10694.                  row to  access this  feature.   (Refer to  the  echo
  10695.                  command help screen for a complete list.)
  10696.  
  10697.             12.  Argument lists passed to a child process can be much
  10698.                  larger than  are allowed  under UNIX.   The  UNIX  C
  10699.                  shell  allows  only  roughly  6K  characters  to  be
  10700.                  passed, depending  on the revision level; this shell
  10701.                  allows up  to 64K  to be  passed to  a child process
  10702.                  under OS/2  or 32K  under NT,  the kernel  limits on
  10703.                  these systems.  There is no command line limit to an
  10704.                  internal  command   such  as   echo.    This  is  of
  10705.                  particular  importance   when  wildcarding  is  used
  10706.                  heavily.
  10707.  
  10708.  
  10709.  
  10710.  
  10711.  
  10712.                                      Page 166
  10713.  
  10714.                                                                 Compatibility
  10715.  
  10716.  
  10717.             13.  Quoted strings are shown in the history list exactly
  10718.                  as they  would have to be typed.  (The Berkeley UNIX
  10719.                  C shell  marked a character as quoted by setting its
  10720.                  high-order bit; setting aside portability issues, it
  10721.                  had the  side-effect of  not being  visible  in  the
  10722.                  history list.)
  10723.  
  10724.             14.  Parentheses in  an argument  list to  an  executable
  10725.                  statement need  not be  escaped, so long as they are
  10726.                  matched.  Semicolons, i/o redirection symbols, etc.,
  10727.                  inside these  parentheses are treated simply as text
  10728.                  and are passed straight through to the application.
  10729.  
  10730.             15.  The  ``:b''   (base)  and   ``:#''  (count)  editing
  10731.                  operators are new.
  10732.  
  10733.             16.  The   indefinite   directory   wildcard   construct,
  10734.                  ``...'', is new.
  10735.  
  10736.  
  10737.  
  10738.             Restrictions and unimplemented features:
  10739.  
  10740.             1.   History  references  as  way  of  picking  up  alias
  10741.                  arguments are  not supported.   Procedures should be
  10742.                  used instead.
  10743.  
  10744.             2.   Job control  is not  supported.   Job control is not
  10745.                  currently feasible  under Windows NT or OS/2 because
  10746.                  once one thread from any process within a window has
  10747.                  started to  read the  keyboard, the  read can not be
  10748.                  interrupted.  (Fortunately, one can always open more
  10749.                  windows.)
  10750.  
  10751.             3.   The use  of ``\!'' inside a prompt string to get the
  10752.                  statement number  is  not  supported.    Use  $@  or
  10753.                  $stmtnumber instead.
  10754.  
  10755.             4.   The following  statements, all  fairly  specific  to
  10756.                  UNIX,  are  not  supported:    alloc,  glob,  limit,
  10757.                  notify, stop.
  10758.  
  10759.             5.   The comment  character, #,  must be followed by some
  10760.                  white space  to be  considered the  start of a valid
  10761.                  comment.   (That's because # is a legal character in
  10762.                  a filename under both NT and OS/2.)
  10763.  
  10764.  
  10765.  
  10766.             Adaptation for OS/2 and NT:
  10767.  
  10768.             1.   OS/2 and  Win32 NT do not provide a fork( ) call for
  10769.                  inexpensively  cloning  an  independent  copy  of  a
  10770.                  running process,  complete  with  its  own  separate
  10771.  
  10772.  
  10773.  
  10774.                                      Page 167
  10775.  
  10776.      Compatibility
  10777.  
  10778.  
  10779.                  memory image.  Instead, OS/2 and NT provide a faster
  10780.                  alternative  called   threads,  which   creates   an
  10781.                  separately scheduled  flow of  control  through  the
  10782.                  memory space of a single process.
  10783.  
  10784.                  In general, the Hamilton C shell spawns a new thread
  10785.                  anywhere the Berkeley UNIX C shell would have used a
  10786.                  process.   Using a  new  thread  instead  of  a  new
  10787.                  invocation of  the Hamilton  C shell  saves  over  a
  10788.                  second each  time.   Individual threads manage their
  10789.                  own notions  of current directories and current disk
  10790.                  and certain  per-thread variables but the dictionary
  10791.                  of aliases,  procedures and most variables is shared
  10792.                  among all threads.
  10793.  
  10794.                  The result is that background activities and C shell
  10795.                  scripts can  change  variables,  define  procedures,
  10796.                  etc., for  use by  the other  threads.  For example,
  10797.                  procedures can  be written  as self-loading scripts.
  10798.                  (See the whereis.csh file for an example.)
  10799.  
  10800.             2.   OS/2 and  NT conventions  are followed:   either the
  10801.                  ``\'' or  the ``/''  characters can  be  used  in  a
  10802.                  filename; the ``^'' character is normally the escape
  10803.                  character;  directories   in  the  PATH  environment
  10804.                  variable are separated by semicolons, etc.
  10805.  
  10806.             3.   Labels cannot be a single letter.  (This is to avoid
  10807.                  confusing the  drive letter  in the  pathname of  an
  10808.                  executable file as a label.)
  10809.  
  10810.             4.   Since  OS/2   and  most   NT  filenames   are  case-
  10811.                  insensitive, they  are routinely translated to lower
  10812.                  case  for   better  readability.     (This   can  be
  10813.                  overridden using the MIXEDCASEDRIVES variable.)
  10814.  
  10815.             5.   Executable files  are recognized by their extension.
  10816.                  The following  extensions are  recognized  (in  this
  10817.                  order):   .csh, .exe,  .com, .cmd, .bat.  .csh files
  10818.                  are interpreted  as C shell scripts by a new thread,
  10819.                  .exe and .com files are executed with the DosExecPgm
  10820.                  and DosStartSession  kernel functions  under OS/2 or
  10821.                  with the  CreateProcess kernel  function  under  NT,
  10822.                  .cmd  files  are  interpreted  by  a  child  process
  10823.                  running cmd.exe,  and .bat  files are  passed  to  a
  10824.                  Virtual DOS  machine (VDM)  under  OS/2  2.x  or  to
  10825.                  cmd.exe under NT.
  10826.  
  10827.             6.   PROMPT1 and  PROMPT2 variables  are used  to set the
  10828.                  primary and  secondary prompt  strings.   Using  the
  10829.                  UNIX C  shell variable  PROMPT would have conflicted
  10830.                  with cmd.exe's  use of  the same name and would have
  10831.                  meant a  nonsense  prompt  string  any  time  either
  10832.                  command processor was invoked by other.
  10833.  
  10834.  
  10835.  
  10836.                                      Page 168
  10837.  
  10838.                                                                 Compatibility
  10839.  
  10840.  
  10841.             7.   The following  startup  or  other  files  have  been
  10842.                  renamed to  be more  consistent  with  OS/2  and  NT
  10843.                  filename conventions:   ~/.cshrc  as  ~\startup.csh;
  10844.                  ~/.login as  ~\login.csh; ~/.logout as ~\logout.csh;
  10845.                  and ~/.history  as ~\history.csh.   The  ~\login.csh
  10846.                  file  is   read  before,   rather  than   after  the
  10847.                  ~\startup.csh file.   When  starting the  shell as a
  10848.                  new session,  very little  environmental information
  10849.                  may be  passed; the  login.csh is  more usefully the
  10850.                  first file  read in this situation.  When starting a
  10851.                  subshell,  either   from  csh.exe  or  cmd.exe,  the
  10852.                  environment is presumably already set up.
  10853.  
  10854.  
  10855.  
  10856.             Berkeley Compatibility Mode:
  10857.  
  10858.                  Berkeley Compatibility  Mode provides  fairly strict
  10859.             compatibility with  the original  BSD C shell.  Triggered
  10860.             by trying  to run a script that starts with #!/bin/csh or
  10861.             interactively if the shell is invoked with the -B option,
  10862.             it causes  the C  shell to  process statements  in a more
  10863.             fully Berkeley-compatible  fashion.  (Scripts that do not
  10864.             start with  #!/bin/csh will  still be processed according
  10865.             to Hamilton  C shell rules, even if the -B option is used
  10866.             to  request  Berkeley  compatibility  interactively.)  In
  10867.             compatibility mode:
  10868.  
  10869.             1.   The status  variable will  reflect the  return  code
  10870.                  from  the  rightmost  stage  of  a  pipeline.    The
  10871.                  tailstatus variable will be ignored.
  10872.  
  10873.             2.   All the  shell variables will be snapshotted and all
  10874.                  new variables made local to the thread.
  10875.  
  10876.             3.   Berkeley-style $var[...]  indexing notation  will be
  10877.                  used,  where  the  indexing  is  by  word  selection
  10878.                  operators (like the :-editing operators) rather than
  10879.                  by expression.
  10880.  
  10881.             4.   All variable  arrays (except  argv) will  start with
  10882.                  element 1.  Accessing element 0 will give a null.
  10883.  
  10884.             5.   $0 or  $argv[0] will  be the scriptname.  $argv will
  10885.                  be the  rest of  the argument  vector.   The bsdargv
  10886.                  variable will be ignored.
  10887.  
  10888.             6.   The #  character will  not need  to be  followed  by
  10889.                  white space to be considered the start of a comment.
  10890.  
  10891.             7.   The patterns  in a  case test (inside a switch) will
  10892.                  be strings  and need  not  be  quoted,  rather  than
  10893.                  arbitrary expressions.   Also,  the switch  value is
  10894.                  evaluated as  a wordlist  which may contain variable
  10895.  
  10896.  
  10897.  
  10898.                                      Page 169
  10899.  
  10900.      Compatibility
  10901.  
  10902.  
  10903.                  or command  substitutions  and  wildcards  and  then
  10904.                  rendered as a string.
  10905.  
  10906.             8.   endif and  endsw will  be predefined aliases for end
  10907.                  (but  only   when   closing   an   if   or   switch,
  10908.                  respectively).   breaksw will be a pre-defined alias
  10909.                  for break.
  10910.  
  10911.             9.   ``set foo''  and ``setenv  foo'' will  set foo  to a
  10912.                  null string, not dump its value.
  10913.  
  10914.             10.  / and /= will perform integer division.
  10915.  
  10916.             11.  The right  operand of the =~ and !~ pattern matching
  10917.                  operators will  be taken as a word which may contain
  10918.                  wildcards.
  10919.  
  10920.             12.  In an  expression, a  variable name must be preceded
  10921.                  by $.   If  it isn't,  it'll be  taken as  a literal
  10922.                  string.
  10923.  
  10924.                  These changes  should  allow  most  scripts  to  run
  10925.             without problems.   However,  there will  still be  a few
  10926.             differences:
  10927.  
  10928.             1.   The escape character will still be controlled by the
  10929.                  escapesym  variable  (shared  across  all  threads),
  10930.                  which defaults to ^, not \.
  10931.  
  10932.             2.   Environmental  variables   will  still   be  shared.
  10933.                  Changing them  in a  script will change them as seen
  10934.                  by the parent.
  10935.  
  10936.             3.   The special  meaning of  several break statements on
  10937.                  one line will not be supported.
  10938.  
  10939.             4.   unset and unsetenv still do not accept patterns.
  10940.  
  10941.             5.   The following  commands are not supported: bg, exec,
  10942.                  fg, glob,  jobs, limit, nice (but eval gives similar
  10943.                  functionality),  nohup,   notify,   stop,   suspend,
  10944.                  unlimit and %job.
  10945.  
  10946.             6.   History references  inside  alias  definitions  will
  10947.                  still not be supported.
  10948.  
  10949.  
  10950.  
  10951.  
  10952.  
  10953.  
  10954.  
  10955.  
  10956.  
  10957.  
  10958.  
  10959.  
  10960.                                      Page 170
  10961.  
  10962.                                                                 Compatibility
  10963.  
  10964.  
  10965.             
  10966.  
  10967.  
  10968.  
  10969.  
  10970.  
  10971.  
  10972.  
  10973.  
  10974.  
  10975.  
  10976.  
  10977.  
  10978.  
  10979.  
  10980.  
  10981.  
  10982.  
  10983.  
  10984.  
  10985.  
  10986.  
  10987.  
  10988.  
  10989.  
  10990.  
  10991.  
  10992.  
  10993.  
  10994.  
  10995.  
  10996.  
  10997.  
  10998.  
  10999.  
  11000.  
  11001.  
  11002.  
  11003.  
  11004.  
  11005.  
  11006.  
  11007.  
  11008.  
  11009.  
  11010.  
  11011.  
  11012.  
  11013.  
  11014.  
  11015.  
  11016.  
  11017.  
  11018.  
  11019.  
  11020.  
  11021.  
  11022.                                      Page 171
  11023.  
  11024.      Language Reference
  11025.  
  11026.  
  11027.             
  11028.  
  11029.  
  11030.                                Language Reference
  11031.  
  11032.  
  11033.  
  11034.  
  11035.             Basic Statements:
  11036.  
  11037.                  Same as cmd.exe:  a file reference + arguments.
  11038.  
  11039.                       Examples: cl -AS -G2 -Zi hello.c
  11040.                                 cp hello.exe c:\os2\bin
  11041.  
  11042.                  Hamilton C  shell maintains  a hash  structure which
  11043.                  allows it  to quickly  search for  a suitable  .csh,
  11044.                  .exe, .com,  .cmd or  (on OS/2  2.x or NT) .bat file
  11045.                  (in that  order) in  each of  as many  as  256  path
  11046.                  directories.   Wildcarding  is  done  by  the  shell
  11047.                  before invoking the child.  Under OS/2, up to 64K of
  11048.                  environmental and  64K of command-line argument data
  11049.                  can be  passed to  a child  process; under NT, up to
  11050.                  32K of  command-line data  can be passed.  These are
  11051.                  the limits of the kernels, not the C shell; there is
  11052.                  no limit  on overall  command line  length in  the C
  11053.                  shell itself.
  11054.  
  11055.  
  11056.             Condition-Testing:
  11057.  
  11058.                  Hamilton  C   shell  provides  both  if  and  switch
  11059.                  constructs.   The if  statement comes  in both short
  11060.                  and long  forms.   The long form uses a then keyword
  11061.                  and allows an optional else clause.  The short form,
  11062.                  which must  be typed on one line, dispenses with the
  11063.                  then keyword  and accepts  a single  statement to be
  11064.                  executed if the condition is satisfied.
  11065.  
  11066.                       if ( <expr> ) then
  11067.                         <statement_list>
  11068.                       else
  11069.                         <statement_list>
  11070.                       end
  11071.  
  11072.                       if ( <expr> ) then
  11073.                         <statement_list>
  11074.                       end
  11075.  
  11076.                       if ( <expr> ) <statement>
  11077.  
  11078.                  Where an expression is expected, a conventional high
  11079.                  level language  syntax is  accepted:    e.g.,  names
  11080.  
  11081.  
  11082.  
  11083.  
  11084.                                      Page 172
  11085.  
  11086.                                                            Language Reference
  11087.  
  11088.  
  11089.                  refer to variables, `*' means multiply, not wildcard
  11090.                  and `>' means greater than, not i/o redirection.
  11091.  
  11092.  
  11093.  
  11094.  
  11095.  
  11096.  
  11097.  
  11098.  
  11099.  
  11100.  
  11101.  
  11102.  
  11103.  
  11104.  
  11105.  
  11106.  
  11107.  
  11108.  
  11109.  
  11110.  
  11111.  
  11112.  
  11113.  
  11114.  
  11115.  
  11116.  
  11117.  
  11118.  
  11119.  
  11120.  
  11121.  
  11122.  
  11123.  
  11124.  
  11125.  
  11126.  
  11127.  
  11128.  
  11129.  
  11130.  
  11131.  
  11132.  
  11133.  
  11134.  
  11135.  
  11136.  
  11137.  
  11138.  
  11139.  
  11140.  
  11141.  
  11142.  
  11143.  
  11144.  
  11145.  
  11146.                                      Page 173
  11147.  
  11148.      Language Reference
  11149.  
  11150.  
  11151.             
  11152.             
  11153.  
  11154.                  if statements  can also  be chained  using the  elif
  11155.                  keyword.   The last  if in the chain may be either a
  11156.                  short- or a long-form if statement.
  11157.  
  11158.                       if ( <expr> ) then
  11159.                         <statement_list>
  11160.                       elif ( <expr> ) then
  11161.                         <statement_list>
  11162.                       else
  11163.                         <statement_list>
  11164.                       end
  11165.  
  11166.                       if ( <expr> ) then
  11167.                         <statement_list>
  11168.                       elif ( <expr> ) then
  11169.                         <statement_list>
  11170.                       end
  11171.  
  11172.                       if ( <expr> ) then
  11173.                         <statement_list>
  11174.                       elif ( <expr> )  <statement>
  11175.  
  11176.                  In a  switch statement,  expressions are compared by
  11177.                  pattern match:   the case expression can be a string
  11178.                  with wildcard characters.  Comparisons are made down
  11179.                  the list  of alternatives  until one  matches.   All
  11180.                  following statements  are executed  until a break is
  11181.                  encountered.   A default  clause is  optional but is
  11182.                  always satisfied if no other case matches.
  11183.  
  11184.                       switch ( <expr> )
  11185.                         case <expr> :
  11186.                            <statement_list>
  11187.                         case <expr> :
  11188.                            <statement_list>
  11189.                         default :
  11190.                            <statement_list>
  11191.                       end
  11192.  
  11193.  
  11194.  
  11195.  
  11196.  
  11197.  
  11198.  
  11199.  
  11200.  
  11201.  
  11202.  
  11203.  
  11204.  
  11205.  
  11206.  
  11207.  
  11208.                                      Page 174
  11209.  
  11210.                                                            Language Reference
  11211.  
  11212.  
  11213.             
  11214.             
  11215.  
  11216.  
  11217.             Iteration:
  11218.  
  11219.                       foreach <name> ( <word list> )
  11220.                         <statement_list>
  11221.                       end
  11222.  
  11223.                       for <name> = <expr> [ to <expr> ] [ by <expr> ]
  11224.                       do
  11225.                         <statement_list>
  11226.                       end
  11227.  
  11228.                       while ( <expr> )
  11229.                         <statement_list>
  11230.                       end
  11231.  
  11232.                       repeat <number> <statement>
  11233.  
  11234.                       repeat
  11235.                         <statement_list>
  11236.                       until ( <expr> )
  11237.  
  11238.                  The foreach statement is intended for iteration over
  11239.                  a list  of words,  often specified  by  wildcarding.
  11240.                  The  for  statement  offers  the  more  conventional
  11241.                  numeric  iteration.     Multiple  iteration  ranges,
  11242.                  separated by  commas, can  be specified  on the  for
  11243.                  statement.
  11244.  
  11245.  
  11246.             Procedures:
  11247.  
  11248.                       proc <name> ( [ <namelist> ] )
  11249.                         <statement_list>
  11250.                          return [ <expr> ]
  11251.                       end
  11252.  
  11253.                       proc
  11254.  
  11255.                       unproc <namelist>
  11256.  
  11257.                  Procedures  defined   by  the   proc  statement  can
  11258.                  recursively call  other procedures.    They  can  be
  11259.                  referred  to  inside  an  expression  or  as  a  new
  11260.                  command, in which case any value returned is written
  11261.                  to stdout.   The  proc statement  with no  arguments
  11262.                  causes a  list of  the available  procedures  to  be
  11263.                  written.  The unproc statement allows a procedure to
  11264.                  be discarded.
  11265.  
  11266.  
  11267.  
  11268.  
  11269.  
  11270.                                      Page 175
  11271.  
  11272.      Language Reference
  11273.  
  11274.  
  11275.             
  11276.             
  11277.  
  11278.  
  11279.             Aliases:
  11280.  
  11281.                       alias <name> [ = ] ( <word list> )
  11282.                       alias <name> [ = ] <word list>
  11283.  
  11284.                       alias
  11285.                       alias <name>
  11286.  
  11287.                       unalias <namelist>
  11288.  
  11289.                  Aliases can  be referred  to at  the beginning  of a
  11290.                  command and provide a quick, user-defined shorthand.
  11291.                  alias <name>  with no  arguments prints the value of
  11292.                  the name.   alias  without any  arguments prints the
  11293.                  values of all aliases.
  11294.  
  11295.  
  11296.             Variable and Expression Manipulation:
  11297.  
  11298.                       @ <expr>
  11299.                       calc <expr>
  11300.  
  11301.                  The @  and calc  statements will  each calculate the
  11302.                  value of  an expression;  the @  statement  does  it
  11303.                  silently while  the calc statement writes the result
  11304.                  to stdout.
  11305.  
  11306.                       set <named_ref> [ = ] ( <word list> )
  11307.                       set <named_ref> [ = ] <word list>
  11308.                       setenv <named_ref> [ = ] ( <word list> )
  11309.                       setenv <named_ref> [ = ] <word list>
  11310.                       shift [ <name> ]
  11311.  
  11312.                       set
  11313.                       set <name>
  11314.                       setenv
  11315.                       setenv <name>
  11316.  
  11317.                       unset <namelist>
  11318.                       unsetenv <namelist>
  11319.  
  11320.                  The set,  setenv  and  shift  statements  manipulate
  11321.                  variables as  words rather  than expressions.    set
  11322.                  defines a  set variable  that's shared  between  all
  11323.                  threads in  the  shell;  setenv  puts  it  into  the
  11324.                  environment and  inherited by  child processes.  set
  11325.                  or setenv  with no  operands prints  a list  of  all
  11326.                  defined variables  of  that  type.    set <name>  or
  11327.                  setenv <name> with  no arguments  print the value of
  11328.  
  11329.  
  11330.  
  11331.  
  11332.                                      Page 176
  11333.  
  11334.                                                            Language Reference
  11335.  
  11336.  
  11337.                  the named  variable.   unset  or  unsetenv  let  you
  11338.                  discard a variable.
  11339.  
  11340.  
  11341.  
  11342.  
  11343.  
  11344.  
  11345.  
  11346.  
  11347.  
  11348.  
  11349.  
  11350.  
  11351.  
  11352.  
  11353.  
  11354.  
  11355.  
  11356.  
  11357.  
  11358.  
  11359.  
  11360.  
  11361.  
  11362.  
  11363.  
  11364.  
  11365.  
  11366.  
  11367.  
  11368.  
  11369.  
  11370.  
  11371.  
  11372.  
  11373.  
  11374.  
  11375.  
  11376.  
  11377.  
  11378.  
  11379.  
  11380.  
  11381.  
  11382.  
  11383.  
  11384.  
  11385.  
  11386.  
  11387.  
  11388.  
  11389.  
  11390.  
  11391.  
  11392.  
  11393.  
  11394.                                      Page 177
  11395.  
  11396.      Language Reference
  11397.  
  11398.  
  11399.             
  11400.             
  11401.  
  11402.  
  11403.             Local Variables:
  11404.  
  11405.                  The local command lets you define a list of variable
  11406.                  names that you don't to share with other routines or
  11407.                  other processes  or threads  (except your  own child
  11408.                  threads).  When you define a local variable it hides
  11409.                  any previous  definition from  any  outer  statement
  11410.                  list.  (But you are not permitted to redefine any of
  11411.                  the built-in set or setenv variable names.)
  11412.  
  11413.                       local <namelist>
  11414.                       local
  11415.  
  11416.                  The <namelist>  should be  typed with commas between
  11417.                  the names.   When  you create  a new local variable,
  11418.                  its initial  value is  always a null string.  Typing
  11419.                  local with no operands reports the currently defined
  11420.                  and accessible local variables, if any.
  11421.  
  11422.                  When you  spawn a  child thread  either  implicitly,
  11423.                  e.g., to  run the  second or  following stage  of  a
  11424.                  pipeline or  explicitly, by  typing an  ampersand at
  11425.                  the end of a command to run it in the background all
  11426.                  your current  local variables  are  snapshotted  and
  11427.                  copied to the child.  If, following that, either the
  11428.                  parent or  the child  changes the  value of  any  of
  11429.                  these local variables, it affects only its own copy.
  11430.  
  11431.                  Local variables  are automatically discarded as soon
  11432.                  as execution  leaves the  statement nesting level in
  11433.                  which the  variable  was  created.    You  can  also
  11434.                  explicitly discard local variables using the unlocal
  11435.                  command.
  11436.  
  11437.                       unlocal <namelist>
  11438.  
  11439.                  In all other respects, local variables act just like
  11440.                  any other  variables, though  you may  find  they're
  11441.                  slightly faster  since the  shell  doesn't  need  to
  11442.                  semaphore its use of them.
  11443.  
  11444.  
  11445.  
  11446.  
  11447.  
  11448.  
  11449.  
  11450.  
  11451.  
  11452.  
  11453.  
  11454.  
  11455.  
  11456.                                      Page 178
  11457.  
  11458.                                                            Language Reference
  11459.  
  11460.  
  11461.             
  11462.  
  11463.  
  11464.                                   Function Keys
  11465.  
  11466.  
  11467.  
  11468.  
  11469.             setkey command:
  11470.  
  11471.                  The setkey  command lets  you define a list of words
  11472.                  that should  be stuffed  back onto  the command-line
  11473.                  whenever you  press a  particular function key.  The
  11474.                  syntax is  exactly the  same as  used  in  the  set,
  11475.                  setenv and alias commands:
  11476.  
  11477.                       setkey <fkey> [ = ] ( <word list> )
  11478.                       setkey <fkey> [ = ] <word list>
  11479.  
  11480.                  where <fkey>  is any of the function keys f1 (or F1)
  11481.                  through f12 (or F12.)
  11482.  
  11483.                  Typing setkey  with no  operands reports the current
  11484.                  function  key   bindings,   if   any.      Also,   a
  11485.                  corresponding unsetkey  command lets you discard key
  11486.                  bindings:
  11487.  
  11488.                       setkey
  11489.                       unsetkey <fkeylist>
  11490.  
  11491.                  The <fkeylist>  should be  typed with commas between
  11492.                  the keys.  For example:
  11493.  
  11494.                       unsetkey f1, f2
  11495.  
  11496.  
  11497.             Using the Function Keys
  11498.  
  11499.  
  11500.               Key               Meaning                              
  11501.  
  11502.               <Fx>              Clear the command line, post the text
  11503.                                 bound to this key and execute the
  11504.                                 command.
  11505.  
  11506.               Alt-<Fx>          Insert the text bound to this key at
  11507.                                 the cursor location but don't execute
  11508.                                 it yet.
  11509.  
  11510.               Ctrl-<Fx>         Clear the command line and post the
  11511.                                 text bound to this key but don't
  11512.                                 execute it yet.
  11513.  
  11514.  
  11515.  
  11516.  
  11517.  
  11518.                                      Page 179
  11519.  
  11520.      Language Reference
  11521.  
  11522.  
  11523.                  Since the  function key's bound text is written back
  11524.                  into the  command line  inside command  line editor,
  11525.                  the substitution happens ahead of any parsing of the
  11526.                  command line  into words  or  expansion  of  history
  11527.                  ``!...'' or ``%...'' references so it is possible to
  11528.                  meaningfully embed  these kinds  of references  into
  11529.                  the key binding.
  11530.  
  11531.  
  11532.  
  11533.  
  11534.  
  11535.  
  11536.  
  11537.  
  11538.  
  11539.  
  11540.  
  11541.  
  11542.  
  11543.  
  11544.  
  11545.  
  11546.  
  11547.  
  11548.  
  11549.  
  11550.  
  11551.  
  11552.  
  11553.  
  11554.  
  11555.  
  11556.  
  11557.  
  11558.  
  11559.  
  11560.  
  11561.  
  11562.  
  11563.  
  11564.  
  11565.  
  11566.  
  11567.  
  11568.  
  11569.  
  11570.  
  11571.  
  11572.  
  11573.  
  11574.  
  11575.  
  11576.  
  11577.  
  11578.  
  11579.  
  11580.                                      Page 180
  11581.  
  11582.                                                            Language Reference
  11583.  
  11584.  
  11585.  
  11586.                             Miscellaneous Statements
  11587.  
  11588.  
  11589.               Statement                   Function                   
  11590.  
  11591.               <drive>:                    Change current drive.
  11592.  
  11593.               <label>:  <statement>       Define a label.
  11594.  
  11595.               ( <statement_list> )        Group a list of statements,
  11596.                                           saving and restoring the
  11597.                                           current directory during
  11598.                                           execution
  11599.  
  11600.               break [ <name> ]            Exit from the named or, by
  11601.                                           default, the innermost
  11602.                                           switch, foreach, for, while
  11603.                                           or repeat statement.
  11604.  
  11605.               continue [ <name> ]         Continue with the next
  11606.                                           iteration of the named or
  11607.                                           innermost foreach, for,
  11608.                                           while or repeat.
  11609.  
  11610.               exit [ <expr> ]             Exit from this thread or,
  11611.                                           if this is the main thread,
  11612.                                           from the C shell.
  11613.  
  11614.               goto <name>                 Continue at the labeled
  11615.                                           statement.
  11616.  
  11617.               onintr <statement>          Define the action to be
  11618.                                           taken if an interrupt is
  11619.                                           signaled.  Whatever's
  11620.                                           running is interrupted all
  11621.                                           the way back up to the
  11622.                                           block in which the onintr
  11623.                                           was defined.  That
  11624.                                           statement is run in the
  11625.                                           current thread and
  11626.                                           execution continues with
  11627.                                           the next statement in the
  11628.                                           block where the onintr was
  11629.                                           defined.  When execution
  11630.                                           leaves a block in which an
  11631.                                           onintr is defined, the
  11632.                                           previous onintr (if any)
  11633.                                           again takes effect.  To
  11634.                                           ignore or defer interrupts,
  11635.                                           use the irqmask variable.
  11636.  
  11637.  
  11638.  
  11639.  
  11640.  
  11641.  
  11642.                                      Page 181
  11643.  
  11644.      Language Reference
  11645.  
  11646.  
  11647.               source <wordargs>           Read and process statements
  11648.                                           from a file as if they were
  11649.                                           typed into this thread.
  11650.  
  11651.               time <statement>            Execute the statement and
  11652.                                           report how long it took.
  11653.  
  11654.               #                           Comment text up to the end
  11655.                                           of the line.  (To be
  11656.                                           recognized as a valid
  11657.                                           comment, the # must be
  11658.                                           followed by at least one
  11659.                                           space or tab.)
  11660.  
  11661.  
  11662.  
  11663.  
  11664.  
  11665.  
  11666.  
  11667.  
  11668.  
  11669.  
  11670.  
  11671.  
  11672.  
  11673.  
  11674.  
  11675.  
  11676.  
  11677.  
  11678.  
  11679.  
  11680.  
  11681.  
  11682.  
  11683.  
  11684.  
  11685.  
  11686.  
  11687.  
  11688.  
  11689.  
  11690.  
  11691.  
  11692.  
  11693.  
  11694.  
  11695.  
  11696.  
  11697.  
  11698.  
  11699.  
  11700.  
  11701.  
  11702.  
  11703.  
  11704.                                      Page 182
  11705.  
  11706.                                                            Language Reference
  11707.  
  11708.  
  11709.             
  11710.  
  11711.  
  11712.                              Statement Relationships
  11713.  
  11714.  
  11715.             In order of decreasing precedence:
  11716.  
  11717.               Operator                    Meaning                    
  11718.  
  11719.               ( )                         Grouping
  11720.  
  11721.               >     >!     >&     >&!     >>     >>!     >>&     >>&!
  11722.                                           <     <<
  11723.                                           I/O Redirection
  11724.  
  11725.               |     |&                    Piping (stdout only or
  11726.                                           stdout + stderr) between
  11727.                                           concurrent operations
  11728.  
  11729.               ... &                       Background thread or
  11730.                                           process
  11731.  
  11732.               &&     ||                   Conditional execution:
  11733.                                           only if first succeeds or
  11734.                                           only if first fails
  11735.  
  11736.               ;                           Serial execution
  11737.  
  11738.  
  11739.  
  11740.  
  11741.                                  I/O Redirection
  11742.  
  11743.  
  11744.               Operator                    Meaning                    
  11745.  
  11746.               >     >!     >&     >&!     Output to a file (`!'
  11747.                                           allows an existing file to
  11748.                                           be overwritten; `&'
  11749.                                           redirects both stdout and
  11750.                                           stderr.)
  11751.  
  11752.               >>     >>!     >>&     >>&! Append to a file
  11753.  
  11754.               <                           In from a file
  11755.  
  11756.               <<  <string>                Inline data: the text on
  11757.                                           the following lines, up to
  11758.                                           the line containing only
  11759.                                           the specified <string> will
  11760.                                           be fed as stdin to the
  11761.                                           statement.  Unless part of
  11762.                                           <string> is escaped or
  11763.  
  11764.  
  11765.  
  11766.                                      Page 183
  11767.  
  11768.      Language Reference
  11769.  
  11770.  
  11771.                                           single, double or
  11772.                                           backquoted, command and
  11773.                                           variable substitution will
  11774.                                           be done on the inline text.
  11775.  
  11776.  
  11777.                  The grammar  is completely  recursive, so statements
  11778.                  of  arbitrary   complexity  can  be  freely  nested,
  11779.                  conditionally executed, piped or redirected.
  11780.  
  11781.  
  11782.  
  11783.  
  11784.  
  11785.  
  11786.  
  11787.  
  11788.  
  11789.  
  11790.  
  11791.  
  11792.  
  11793.  
  11794.  
  11795.  
  11796.  
  11797.  
  11798.  
  11799.  
  11800.  
  11801.  
  11802.  
  11803.  
  11804.  
  11805.  
  11806.  
  11807.  
  11808.  
  11809.  
  11810.  
  11811.  
  11812.  
  11813.  
  11814.  
  11815.  
  11816.  
  11817.  
  11818.  
  11819.  
  11820.  
  11821.  
  11822.  
  11823.  
  11824.  
  11825.  
  11826.  
  11827.  
  11828.                                      Page 184
  11829.  
  11830.                                                            Language Reference
  11831.  
  11832.  
  11833.             
  11834.  
  11835.  
  11836.                               Expression Operators
  11837.  
  11838.  
  11839.             In order of decreasing precedence:
  11840.  
  11841.               Operator          Meaning                            
  11842.  
  11843.               ( )               Grouping or Procedure call
  11844.                                 arguments
  11845.  
  11846.               { }               Run the enclosed statement list and
  11847.                                 return 1 if it succeeds or 0
  11848.                                 otherwise.
  11849.  
  11850.               [ ]               Array indexing.  (The first element
  11851.                                 is element 0.)
  11852.  
  11853.               -A   -D   -H   -R   -S   -d   -e   -f   -o   -w   -x
  11854.                                 -z
  11855.                                 File system tests
  11856.  
  11857.               ++   --           Prefix and postfix
  11858.                                 increment/decrement
  11859.  
  11860.               ~   -   !   +     Bitwise, arithmetic and logical
  11861.                                 complements and unary plus
  11862.  
  11863.               **                Exponentiation
  11864.  
  11865.               *   /   %   //    Multiplication, Division, Remainder
  11866.                                 and Integer Division
  11867.  
  11868.               +   -             Addition and Subtraction
  11869.  
  11870.               <<   >>           Bit Shifting
  11871.  
  11872.               ==   !=   =~   !~   <   <=   >=   >   Relation-
  11873.                                 testing and pattern-matching
  11874.                                 operators
  11875.  
  11876.               &                 Bit And
  11877.  
  11878.               ^                 Bit Xor
  11879.  
  11880.               |                 Bit Or
  11881.  
  11882.               &&                Logical And
  11883.  
  11884.               ||                Logical Or
  11885.  
  11886.               ?:                Conditional selection
  11887.  
  11888.  
  11889.  
  11890.                                      Page 185
  11891.  
  11892.      Language Reference
  11893.  
  11894.  
  11895.               =   +=   -=   *=   /=   %=   //=   >>=   <<=   &=
  11896.                                 ^=   |=   **=
  11897.                                 Assignment operators
  11898.  
  11899.             Expressions result  in sensible  types, considering  both
  11900.             the types  and the  values of the operands.  For example,
  11901.             10/2 returns  the integer 5 but 5/2 produces the floating
  11902.             point value 2.5.  Also, the integer 1, the floating point
  11903.             value 1.0 and the string ``1'' all compare equal.
  11904.  
  11905.  
  11906.  
  11907.  
  11908.  
  11909.  
  11910.  
  11911.  
  11912.  
  11913.  
  11914.  
  11915.  
  11916.  
  11917.  
  11918.  
  11919.  
  11920.  
  11921.  
  11922.  
  11923.  
  11924.  
  11925.  
  11926.  
  11927.  
  11928.  
  11929.  
  11930.  
  11931.  
  11932.  
  11933.  
  11934.  
  11935.  
  11936.  
  11937.  
  11938.  
  11939.  
  11940.  
  11941.  
  11942.  
  11943.  
  11944.  
  11945.  
  11946.  
  11947.  
  11948.  
  11949.  
  11950.  
  11951.  
  11952.                                      Page 186
  11953.  
  11954.                                                            Language Reference
  11955.  
  11956.  
  11957.             
  11958.  
  11959.  
  11960.                                 File System Tests
  11961.  
  11962.  
  11963.             The operand  of a  file system  test is  interpreted as a
  11964.             word, not an expression, and may involve wildcarding.  If
  11965.             wildcarding produces  more than  one match,  the test  is
  11966.             done on the first one.
  11967.  
  11968.               Prefix Operator   True if                            
  11969.  
  11970.               -A                Archive Bit Set
  11971.  
  11972.               -D     -d         Directory
  11973.  
  11974.               -H                Hidden File or Directory
  11975.  
  11976.               -R                Read-only File or Directory
  11977.  
  11978.               -S                System File or Directory
  11979.  
  11980.               -e                File or Directory Exists
  11981.  
  11982.               -f                Ordinary File
  11983.  
  11984.               -o                Ownership (Same as Existence on an
  11985.                                 OS/2 or NT FAT file system)
  11986.  
  11987.               -r                Readable (Same as ordinary file on
  11988.                                 an OS/2 or NT FAT file system)
  11989.  
  11990.               -w                Writable (Not Read-only and not a
  11991.                                 directory)
  11992.  
  11993.               -x                Executable (Has a .csh, .exe, .com
  11994.                                 or .cmd extension and, if it's an
  11995.                                 .exe or a .com file, appears to be
  11996.                                 a valid OS/2 or NT binary
  11997.                                 executable.)
  11998.  
  11999.               -z                Zero-length File
  12000.  
  12001.  
  12002.                  Example:     if (-d $a) then
  12003.                                 echo $a is a directory
  12004.                               end
  12005.  
  12006.  
  12007.  
  12008.  
  12009.  
  12010.  
  12011.  
  12012.  
  12013.  
  12014.                                      Page 187
  12015.  
  12016.      Language Reference
  12017.  
  12018.  
  12019.             
  12020.  
  12021.  
  12022.                                  Special Devices
  12023.  
  12024.  
  12025.               Name              Use                                
  12026.  
  12027.               aux+              The auxiliary port.
  12028.  
  12029.               clock$+           The OS/2 system clock.
  12030.  
  12031.               con               The OS/2 console.  This is the text
  12032.                                 window the shell is running in.
  12033.                                 Reading from it reads the keyboard;
  12034.                                 writing to it writes to the screen.
  12035.  
  12036.               conin$            The NT console keyboard.  A read-
  12037.                                 only device.
  12038.  
  12039.               conout$           The NT console display.  A write-
  12040.                                 only device.
  12041.  
  12042.               com1 .. com7      The various async communication
  12043.                                 ports you may have.  They can be
  12044.                                 read or written.
  12045.  
  12046.               kbd$              The OS/2 keyboard.  A read-only
  12047.                                 device.
  12048.  
  12049.               lpt1 .. lpt4+     The line printer ports.
  12050.  
  12051.               nul               The null device.  Reads return end-
  12052.                                 of-file; writes are discarded.
  12053.  
  12054.               prn               The print spooler queue.
  12055.  
  12056.               pointer$+         The OS/2 mouse and on-screen
  12057.                                 pointer combination.  Reads from
  12058.                                 the mouse; writes to the screen.
  12059.  
  12060.               screen$           The OS/2 text window. A write-only
  12061.                                 device.
  12062.  
  12063.  
  12064.                  Hamilton C  shell recognizes the OS/2 and NT special
  12065.                  device names regardless of whether they are typed in
  12066.                  upper or  lower case and regardless of whether there
  12067.                  is a trailing colon.  For example, COM1: is the same
  12068.                  as COM1  is the same as com1.  Remember to quote the
  12069.                  device name if it has a dollar sign at the end so it
  12070.                  won't be  misinterpreted as  the start of a variable
  12071.                  reference.
  12072.  
  12073.  
  12074.  
  12075.  
  12076.                                      Page 188
  12077.  
  12078.                                                            Language Reference
  12079.  
  12080.  
  12081.                  Not all  devices will be installed on any particular
  12082.                  machine.  Also, the exact behavior of any device may
  12083.                  depend which  manufacturer  supplied  it.    Devices
  12084.                  marked with  + should  only be  accessed  with  some
  12085.                  caution.
  12086.  
  12087.  
  12088.  
  12089.  
  12090.  
  12091.  
  12092.  
  12093.  
  12094.  
  12095.  
  12096.  
  12097.  
  12098.  
  12099.  
  12100.  
  12101.  
  12102.  
  12103.  
  12104.  
  12105.  
  12106.  
  12107.  
  12108.  
  12109.  
  12110.  
  12111.  
  12112.  
  12113.  
  12114.  
  12115.  
  12116.  
  12117.  
  12118.  
  12119.  
  12120.  
  12121.  
  12122.  
  12123.  
  12124.  
  12125.  
  12126.  
  12127.  
  12128.  
  12129.  
  12130.  
  12131.  
  12132.  
  12133.  
  12134.  
  12135.  
  12136.  
  12137.  
  12138.                                      Page 189
  12139.  
  12140.      Language Reference
  12141.  
  12142.  
  12143.             
  12144.  
  12145.  
  12146.                         Wildcarding and Pattern Matching
  12147.  
  12148.  
  12149.               Characters        Meaning                            
  12150.  
  12151.               ?                 Match any single character,
  12152.                                 including `.' but not `\' or '/'.
  12153.  
  12154.               *                 Match any number of characters,
  12155.                                 including `.' but not '\' or '/'.
  12156.  
  12157.               [a-z]             An example range:  match any
  12158.                                 character a through z.
  12159.  
  12160.               [^a-z]            An example exclusion range: match
  12161.                                 any character not in the set a
  12162.                                 through z.
  12163.  
  12164.               {a,b}c            Alternation:  generate both ac and
  12165.                                 bc.
  12166.  
  12167.               ...               Indefinite Directory:  match any
  12168.                                 number of directory levels -- zero
  12169.                                 or more -- whatever it takes to
  12170.                                 make the rest of the pattern match.
  12171.  
  12172.  
  12173.                  Patterns are  used  both  for  traditional  filename
  12174.                  wildcarding in  word mode  and for examining strings
  12175.                  in  expression   mode.     Patterns   are   nestable
  12176.                  arbitrarily and  a recursive comparison algorithm is
  12177.                  used to  guarantee a  sensible result  no matter how
  12178.                  complex the  pattern.   For example:   *r*  or  even
  12179.                  *\[a-c]*.[ch] operate sensibly.
  12180.  
  12181.                  Filename wildcards  can be  used wherever  a word is
  12182.                  expected and  will match  any filename  except ``.''
  12183.                  and ``..'' unless it's marked ``hidden.''  (To allow
  12184.                  wildcarding to  match hidden files, set nonohidden =
  12185.                  1.)   Quoting the  word prevents wildcarding.  Since
  12186.                  filenames  are   not  case   sensitive,     filename
  12187.                  wildcarding isn't either.
  12188.  
  12189.                  A pattern can also be used  to examine a string in a
  12190.                  switch  statement   or  with   the  ``=~''  (pattern
  12191.                  matches)  and   ``!~''  (pattern  fails)  expression
  12192.                  operators.   In this  context, the  pattern must  be
  12193.                  inside quotes, since otherwise it would be parsed as
  12194.                  an  expression,  with  ``*''  being  viewed  as  the
  12195.                  multiply operator,  etc.   When examining  a  string
  12196.                  with a  pattern that  uses alternation,  the pattern
  12197.  
  12198.  
  12199.  
  12200.                                      Page 190
  12201.  
  12202.                                                            Language Reference
  12203.  
  12204.  
  12205.                  ``matches'' if  any  of  the  alternatives  matches.
  12206.                  When matching strings, case does matter.
  12207.  
  12208.                  When using a pattern to examine a string with ``=~''
  12209.                  or ``!~''  or with a switch, the string being tested
  12210.                  is the left operand and the pattern is on the right.
  12211.  
  12212.  
  12213.  
  12214.  
  12215.  
  12216.  
  12217.  
  12218.  
  12219.  
  12220.  
  12221.  
  12222.  
  12223.  
  12224.  
  12225.  
  12226.  
  12227.  
  12228.  
  12229.  
  12230.  
  12231.  
  12232.  
  12233.  
  12234.  
  12235.  
  12236.  
  12237.  
  12238.  
  12239.  
  12240.  
  12241.  
  12242.  
  12243.  
  12244.  
  12245.  
  12246.  
  12247.  
  12248.  
  12249.  
  12250.  
  12251.  
  12252.  
  12253.  
  12254.  
  12255.  
  12256.  
  12257.  
  12258.  
  12259.  
  12260.  
  12261.  
  12262.                                      Page 191
  12263.  
  12264.      Language Reference
  12265.  
  12266.  
  12267.             
  12268.  
  12269.  
  12270.                                Filename Completion
  12271.  
  12272.  
  12273.  
  12274.  
  12275.             Filename completion  lets you type just the first part of
  12276.             a filename  and have the shell fill in the rest.  The two
  12277.             variations  are  using  the  F  key  for  basic  filename
  12278.             completion or  the D  key if  you want all the duplicates
  12279.             listed.
  12280.  
  12281.  
  12282.               Key               Meaning                              
  12283.  
  12284.               Alt-F or Ctrl-F   Filename completion.  Appending the
  12285.                                 ``*'' wildcard character onto the
  12286.                                 end, use the previous word as a
  12287.                                 wildcard pattern.  If it matches a
  12288.                                 single file, substitute it in with a
  12289.                                 space following.  (If you don't want
  12290.                                 a space following, use the -N option
  12291.                                 when you start the C shell.)
  12292.  
  12293.                                 If there were multiple matches, but
  12294.                                 they all had some common front-part
  12295.                                 that fully ``used up'' the pattern,
  12296.                                 substitute in just that common front-
  12297.                                 part and show it in the color
  12298.                                 specified by the DUPLICATES variable
  12299.                                 (default is green).
  12300.  
  12301.                                 If substitution wasn't possible,
  12302.                                 highlight the pattern in the color
  12303.                                 specified by the MATCHFAIL variable
  12304.                                 (default is bright red).  (Any
  12305.                                 highlighting color is turned off when
  12306.                                 you press the next keystroke.)
  12307.  
  12308.               Alt-D or Ctrl-D   Duplicate completions.  Same
  12309.                                 wildcarding, but if there are
  12310.                                 multiple matches, show them all with
  12311.                                 a space following.  (Here again, if
  12312.                                 you don't want a space following, use
  12313.                                 the -N option when you start the C
  12314.                                 shell.)  If there were no matches,
  12315.                                 highlight the pattern in the color
  12316.                                 specified by the MATCHFAIL variable
  12317.                                 (default is bright red).
  12318.  
  12319.  
  12320.  
  12321.  
  12322.  
  12323.  
  12324.                                      Page 192
  12325.  
  12326.                                                            Language Reference
  12327.  
  12328.  
  12329.                               Command Line Editing
  12330.  
  12331.  
  12332.               Key          Meaning                                   
  12333.  
  12334.  
  12335.  
  12336.  
  12337.  
  12338.  
  12339.  
  12340.  
  12341.  
  12342.  
  12343.  
  12344.  
  12345.  
  12346.  
  12347.  
  12348.  
  12349.  
  12350.  
  12351.  
  12352.  
  12353.  
  12354.  
  12355.  
  12356.  
  12357.  
  12358.  
  12359.  
  12360.  
  12361.  
  12362.  
  12363.  
  12364.  
  12365.  
  12366.  
  12367.  
  12368.  
  12369.  
  12370.  
  12371.  
  12372.  
  12373.  
  12374.  
  12375.  
  12376.  
  12377.  
  12378.  
  12379.  
  12380.  
  12381.  
  12382.  
  12383.  
  12384.  
  12385.  
  12386.                                      Page 193
  12387.  
  12388.      Language Reference
  12389.  
  12390.  
  12391.               <Enter>      Accept the command as typed.  Move to the
  12392.                            end (if not there already) and carriage
  12393.                            return to a new line.
  12394.               <Home>       Beginning of command line.
  12395.               <End>        End of command line.
  12396.               <Up>         Up one command in the history list.  Each
  12397.                            time it's pressed, it displays the
  12398.                            preceding entry in the history list.  Any
  12399.                            ``!...'' or ``%...'' history references in
  12400.                            the original text will have been fixed up
  12401.                            unless it was the immediately preceding
  12402.                            command and it had one these references
  12403.                            that failed.  If already at the first
  12404.                            entry, the command line is highlighted in
  12405.                            bright red.
  12406.               <Down>       Down one command line in the history list.
  12407.                            If already at the latest entry, the
  12408.                            command line is highlighted in bright red.
  12409.               <Left>       One character left.
  12410.               <Right>      One character right.
  12411.               Ctrl-<Home>  Move to the upper-leftmost character in
  12412.                            the current screenful if the command is
  12413.                            long enough that it actually wraps across
  12414.                            several screens.
  12415.               Ctrl-<End>   Move to the lower-rightmost character in
  12416.                            the current screenful.
  12417.               Ctrl-<Up>    Up one row on the screen if the command is
  12418.                            long enough that it runs over a row.
  12419.               Ctrl-<Down>  Down one row on the screen.
  12420.               Ctrl-<Left>  Backup word.
  12421.               Ctrl-<Right> Forward word.
  12422.               Alt-<Home>   Delete all preceding characters on the
  12423.                            command line.
  12424.               Alt-<End>    Delete all following characters.
  12425.               Alt-<Up>     Delete up one row on the screen if the
  12426.                            command runs over a row.
  12427.               Alt-<Down>   Delete down one row.
  12428.               Alt-<Left>   Delete preceding word.
  12429.               Ctrl-<Backspace>
  12430.               Alt-<Right>  Delete following word.
  12431.               <Insert>     Toggle insert/overstrike mode.  When
  12432.                            inserting, the cursor is slightly thicker.
  12433.               Ctrl-<Insert>     Insert the next word from the last
  12434.                            section of deleted text.  When it reaches
  12435.                            the end of the deleted text, it starts
  12436.                            over.
  12437.               Alt-<Insert> Insert all the rest of the previously
  12438.                            deleted text.
  12439.               <PageUp>     Backup to one past the last history
  12440.                            reference.  (Repeatedly typing <PageUp>
  12441.                            <Enter> is a convenient way of picking up
  12442.                            a whole series of commands from history.)
  12443.               <PageDown>   Forward to the newest entry in the history
  12444.                            list.
  12445.  
  12446.  
  12447.  
  12448.                                      Page 194
  12449.  
  12450.                                                            Language Reference
  12451.  
  12452.  
  12453.               <Esc>        Clear the command line.
  12454.  
  12455.               Note:  Users lacking separate arrow keys must press
  12456.               Ctrl-Shift instead of Alt.
  12457.  
  12458.             
  12459.  
  12460.  
  12461.  
  12462.  
  12463.  
  12464.  
  12465.  
  12466.  
  12467.  
  12468.  
  12469.  
  12470.  
  12471.  
  12472.  
  12473.  
  12474.  
  12475.  
  12476.  
  12477.  
  12478.  
  12479.  
  12480.  
  12481.  
  12482.  
  12483.  
  12484.  
  12485.  
  12486.  
  12487.  
  12488.  
  12489.  
  12490.  
  12491.  
  12492.  
  12493.  
  12494.  
  12495.  
  12496.  
  12497.  
  12498.  
  12499.  
  12500.  
  12501.  
  12502.  
  12503.  
  12504.  
  12505.  
  12506.  
  12507.  
  12508.  
  12509.  
  12510.                                      Page 195
  12511.  
  12512.      Language Reference
  12513.  
  12514.  
  12515.  
  12516.                                  History Recall
  12517.  
  12518.  
  12519.               Command           Meaning                            
  12520.  
  12521.               !!                Last command
  12522.  
  12523.               !^                First argument word of last command
  12524.  
  12525.               !$                Last word of last command
  12526.  
  12527.               !*                All arguments of last command
  12528.  
  12529.               !n                Command n
  12530.  
  12531.               !-n               nth command from the last
  12532.  
  12533.               !str              Last command starting with str
  12534.  
  12535.               !?str?            Last command containing str
  12536.  
  12537.               %str1%str2%       Substitute str2 for str1 in last
  12538.                                 command. (Used only at the
  12539.                                 beginning of a line.)
  12540.  
  12541.  
  12542.                  History recall  allows a  previous statement  to  be
  12543.                  quickly recalled  and re-executed.  It's a very fast
  12544.                  shorthand, especially in the edit/compile/debug loop
  12545.                  or to  fix a  typo.  For convenience, ``!'' is taken
  12546.                  as an ordinary character if followed by white space,
  12547.                  ``='', ``~'' or ``(''.
  12548.  
  12549.                  If you  want, you can choose different characters to
  12550.                  introduce  history   references  by   changing   the
  12551.                  histchars variable.
  12552.  
  12553.  
  12554.  
  12555.                                Command Completion
  12556.  
  12557.  
  12558.             Command completion  lets you type just part of a previous
  12559.             command and  have the  shell fill  in the  rest.  As with
  12560.             filename  completion,   if  no   match  is  found,  color
  12561.             highlighting  as   defined  by   the  MATCHFAIL  variable
  12562.             (default is  bright  red)  will  be  used.    Consecutive
  12563.             depressions cause  the search to continue on back through
  12564.             the history list.
  12565.  
  12566.               Key               Meaning                            
  12567.  
  12568.  
  12569.  
  12570.  
  12571.  
  12572.                                      Page 196
  12573.  
  12574.                                                            Language Reference
  12575.  
  12576.  
  12577.               Ctrl-<Enter>      Search for the last command that
  12578.                                 starts with the characters in the
  12579.                                 previous word.
  12580.  
  12581.               Alt-<Enter>       Search for the last command that
  12582.                                 contains the characters in the
  12583.                                 previous word anywhere on the
  12584.                                 command line.
  12585.  
  12586.  
  12587.  
  12588.  
  12589.  
  12590.  
  12591.  
  12592.  
  12593.  
  12594.  
  12595.  
  12596.  
  12597.  
  12598.  
  12599.  
  12600.  
  12601.  
  12602.  
  12603.  
  12604.  
  12605.  
  12606.  
  12607.  
  12608.  
  12609.  
  12610.  
  12611.  
  12612.  
  12613.  
  12614.  
  12615.  
  12616.  
  12617.  
  12618.  
  12619.  
  12620.  
  12621.  
  12622.  
  12623.  
  12624.  
  12625.  
  12626.  
  12627.  
  12628.  
  12629.  
  12630.  
  12631.  
  12632.  
  12633.  
  12634.                                      Page 197
  12635.  
  12636.      Language Reference
  12637.  
  12638.  
  12639.             
  12640.  
  12641.  
  12642.                                      Quoting
  12643.  
  12644.  
  12645.               String            Meaning                            
  12646.  
  12647.               '...'             Literal character string.  Only do
  12648.                                 history substitutions.
  12649.  
  12650.               "..."             Single word.  Typically used if
  12651.                                 there are embedded blanks or
  12652.                                 wildcard characters you want
  12653.                                 treated as ordinary.  Has no effect
  12654.                                 on command or variable
  12655.                                 substitutions:  they're still done.
  12656.  
  12657.               `...`             Command substitution.  Evaluate the
  12658.                                 string as a separate command and
  12659.                                 substitute its output back onto the
  12660.                                 command line.  Newlines are turned
  12661.                                 into spaces and Ansi escape
  12662.                                 sequences (for highlighting, etc.)
  12663.                                 are filtered out.
  12664.  
  12665.               ^                 Quote just the next character.  Use
  12666.                                 to remove any special meaning from
  12667.                                 the next character, to specify a
  12668.                                 character by its binary value or to
  12669.                                 specify one following non-printable
  12670.                                 characters.  If the NewLine
  12671.                                 character at the end of a line is
  12672.                                 quoted this way, it's treated as
  12673.                                 ordinary white space.  (You can
  12674.                                 choose a different escape character
  12675.                                 by changing the escapesym
  12676.                                 variable.)
  12677.  
  12678.  
  12679.  
  12680.  
  12681.                                 Escape Sequences
  12682.  
  12683.  
  12684.               String            Meaning                            
  12685.  
  12686.               ^a                Audible alert (bell)
  12687.               ^b                Backspace
  12688.               ^f                Form Feed
  12689.               ^n                New Line
  12690.               ^r                Carriage Return
  12691.               ^t                Tab
  12692.               ^v                Vertical Tab
  12693.  
  12694.  
  12695.  
  12696.                                      Page 198
  12697.  
  12698.                                                            Language Reference
  12699.  
  12700.  
  12701.               ^^                Single escapesym character
  12702.  
  12703.  
  12704.  
  12705.  
  12706.  
  12707.  
  12708.  
  12709.  
  12710.  
  12711.  
  12712.  
  12713.  
  12714.  
  12715.  
  12716.  
  12717.  
  12718.  
  12719.  
  12720.  
  12721.  
  12722.  
  12723.  
  12724.  
  12725.  
  12726.  
  12727.  
  12728.  
  12729.  
  12730.  
  12731.  
  12732.  
  12733.  
  12734.  
  12735.  
  12736.  
  12737.  
  12738.  
  12739.  
  12740.  
  12741.  
  12742.  
  12743.  
  12744.  
  12745.  
  12746.  
  12747.  
  12748.  
  12749.  
  12750.  
  12751.  
  12752.  
  12753.  
  12754.  
  12755.  
  12756.  
  12757.  
  12758.                                      Page 199
  12759.  
  12760.      Language Reference
  12761.  
  12762.  
  12763.             
  12764.             
  12765.             
  12766.             
  12767.  
  12768.  
  12769.                               Variable Substitution
  12770.  
  12771.  
  12772.               Reference                   Meaning                    
  12773.  
  12774.               $var     ${var}             value of variable var
  12775.  
  12776.               $var[<expr>]     ${var[<expr>]}  value of var, indexed
  12777.                                           by an arbitrarily complex
  12778.                                           expression
  12779.  
  12780.               $#var     ${#var}           Number of words in var
  12781.  
  12782.               $?var     ${?var}           1 if var exists; 0
  12783.                                           otherwise
  12784.  
  12785.               $procname( <argument list> )     Procedure reference,
  12786.                                           used as a variable
  12787.                                           substitution.  The
  12788.                                           arguments are expressions,
  12789.                                           separated by commas.  Any
  12790.                                           value returned by the
  12791.                                           procedure will be
  12792.                                           substituted in place.
  12793.  
  12794.               $<                          Pseudo-variable result of
  12795.                                           reading one line from stdin
  12796.                                           each time it's evaluated
  12797.  
  12798.               $*                          Same as $argv
  12799.  
  12800.               $0 .. $9                    Same as $argv[0] ..
  12801.                                           $argv[9]
  12802.  
  12803.  
  12804.                  Variable substitution  is typically used to pass the
  12805.                  value of  a variable  as an  argument to  a command.
  12806.                  For example:  cl -AS -G2 -Zi $a.c
  12807.  
  12808.  
  12809.  
  12810.  
  12811.  
  12812.  
  12813.  
  12814.  
  12815.  
  12816.  
  12817.  
  12818.  
  12819.  
  12820.                                      Page 200
  12821.  
  12822.                                                            Language Reference
  12823.  
  12824.  
  12825.             
  12826.  
  12827.  
  12828.                              Substitution Modifiers
  12829.  
  12830.  
  12831.               Operator                    Meaning                    
  12832.  
  12833.               :n                          nth word
  12834.  
  12835.               :#                          Count the number of words
  12836.  
  12837.               :^                          Word number 1, counting
  12838.                                           from 0
  12839.  
  12840.               :$                          Last word
  12841.  
  12842.               :%                          Word matched by a !?str?
  12843.                                           history search
  12844.  
  12845.               :n-m                        nth through mth words
  12846.  
  12847.               :-n                         0 through nth words
  12848.  
  12849.               :n-                         n through next-to-last
  12850.                                           words
  12851.  
  12852.               :n*                         n through last word
  12853.  
  12854.               :*                          1 through last word
  12855.  
  12856.               :q                          Single quote each word
  12857.  
  12858.               :s/str1/str2/               Substitute str2 for str1
  12859.                                           and then reparse into
  12860.                                           words.  Match failures are
  12861.                                           considered to be errors
  12862.                                           unless ignoreerrors == 2.
  12863.  
  12864.               :S/str1/str2/               Substitute str2 for str1
  12865.                                           but leave it as a single
  12866.                                           string.  Also, failure to
  12867.                                           match is not considered an
  12868.                                           error.
  12869.  
  12870.               :&                          Repeat last substitution
  12871.  
  12872.               :g...                       Global editing:  apply the
  12873.                                           edit operation everywhere
  12874.                                           it matches, not just the
  12875.                                           first occurrence.
  12876.  
  12877.               :x                          Treat each word as a string
  12878.                                           and break it up into words
  12879.  
  12880.  
  12881.  
  12882.                                      Page 201
  12883.  
  12884.      Language Reference
  12885.  
  12886.  
  12887.               :p                          Print the substitution but
  12888.                                           don't execute the
  12889.                                           statement.  (Ignored except
  12890.                                           in history substitutions.)
  12891.  
  12892.  
  12893.                  Substitution  modifiers   can  be   applied  to  any
  12894.                  command, variable  or history  substitution.   Also,
  12895.                  any number in a row can be applied, as desired.
  12896.  
  12897.  
  12898.  
  12899.  
  12900.  
  12901.  
  12902.  
  12903.  
  12904.  
  12905.  
  12906.  
  12907.  
  12908.  
  12909.  
  12910.  
  12911.  
  12912.  
  12913.  
  12914.  
  12915.  
  12916.  
  12917.  
  12918.  
  12919.  
  12920.  
  12921.  
  12922.  
  12923.  
  12924.  
  12925.  
  12926.  
  12927.  
  12928.  
  12929.  
  12930.  
  12931.  
  12932.  
  12933.  
  12934.  
  12935.  
  12936.  
  12937.  
  12938.  
  12939.  
  12940.  
  12941.  
  12942.  
  12943.  
  12944.                                      Page 202
  12945.  
  12946.                                                            Language Reference
  12947.  
  12948.  
  12949.             
  12950.             
  12951.             
  12952.             
  12953.  
  12954.  
  12955.                            Pathname Editing on x\y\z.c
  12956.  
  12957.  
  12958.               Operator  Name      Description            Result    
  12959.  
  12960.               :h        head      Directory containing   x\y
  12961.  
  12962.               :r        root      Path w/o .ext          x\y\z
  12963.  
  12964.               :t        tail      Simple filename        z.c
  12965.  
  12966.               :b        base      Filename w/o .ext      z
  12967.  
  12968.               :e        ext       .ext w/o the ``.''     c
  12969.  
  12970.               :f        fullpath  Fully-qualified name   d:\bob\x\y\z
  12971.               .c
  12972.  
  12973.  
  12974.                  Pathname editing  can be  applied  to  any  command,
  12975.                  variable or  history substitution.  Also, any number
  12976.                  of pathname  editing operations  can be applied, one
  12977.                  after the other, to a given substitution.
  12978.  
  12979.                  Example:  echo $path:gt
  12980.  
  12981.  
  12982.  
  12983.  
  12984.  
  12985.  
  12986.  
  12987.  
  12988.  
  12989.  
  12990.  
  12991.  
  12992.  
  12993.  
  12994.  
  12995.  
  12996.  
  12997.  
  12998.  
  12999.  
  13000.  
  13001.  
  13002.  
  13003.  
  13004.  
  13005.  
  13006.                                      Page 203
  13007.  
  13008.      Language Reference
  13009.  
  13010.  
  13011.             
  13012.  
  13013.  
  13014.  
  13015.  
  13016.  
  13017.  
  13018.  
  13019.  
  13020.  
  13021.  
  13022.  
  13023.  
  13024.  
  13025.  
  13026.  
  13027.  
  13028.  
  13029.  
  13030.  
  13031.  
  13032.  
  13033.  
  13034.  
  13035.  
  13036.  
  13037.  
  13038.  
  13039.  
  13040.  
  13041.  
  13042.  
  13043.  
  13044.  
  13045.  
  13046.  
  13047.  
  13048.  
  13049.  
  13050.  
  13051.  
  13052.  
  13053.  
  13054.  
  13055.  
  13056.  
  13057.  
  13058.  
  13059.  
  13060.  
  13061.  
  13062.  
  13063.  
  13064.  
  13065.  
  13066.  
  13067.  
  13068.                                      Page 204
  13069.  
  13070.                                                          Predefined Variables
  13071.  
  13072.  
  13073.  
  13074.                        Environmental Variables Recognized
  13075.  
  13076.  
  13077.             Name          Default  Use                                  
  13078.  
  13079.             ADDITIONSBright Green  Lines added found by diff.
  13080.  
  13081.             CDPATH                 List of directories to search for
  13082.                                    the subdirectory specified as the
  13083.                                    new current directory.
  13084.  
  13085.             COLORS White on Black  Normal screen colors.
  13086.  
  13087.             COMSPEC                Usually, this is the pathname of
  13088.                                    cmd.exe.  If you set it to point
  13089.                                    to the C shell, e.g., so other
  13090.                                    programs will invoke the C shell
  13091.                                    rather than cmd.exe, the C shell
  13092.                                    will try to look through the
  13093.                                    search path for cmd.exe if it
  13094.                                    needs to run a .cmd file.
  13095.  
  13096.             CSHOPTIONS             Default set of command line
  13097.                                    options to be pasted ahead of any
  13098.                                    other command line options passed
  13099.                                    to csh.exe.
  13100.  
  13101.             DELETIONS  Bright Red  Lines deleted found by diff.
  13102.  
  13103.             DIRECTORIES    Bright  Directories listed by ls.
  13104.  
  13105.             DRIVEMASK              Used by du.exe, pwd.exe and vl.exe
  13106.                                    to limit the default list of
  13107.                                    drives it will report on.  Written
  13108.                                    as a list of alphabetic characters
  13109.                                    representing the drives you want
  13110.                                    listed; ranges are allowed.  If
  13111.                                    you don't define this variable,
  13112.                                    all drives beginning with C: are
  13113.                                    normally reported.
  13114.  
  13115.             DUPLICATES      Green  When filename completion matches
  13116.                                    matches more than one name.
  13117.  
  13118.             ESCAPESYM           ^  Character to be interpreted as a
  13119.                                    literal escape character.  Placed
  13120.                                    in the environment only if it is
  13121.                                    not the default circumflex.
  13122.  
  13123.             FOREIGNFILESBright Red Filetypes in a tar file that have
  13124.                                    no counterpart on OS/2.
  13125.  
  13126.             HIGHLIGHT      Bright  Current disk or directory.
  13127.  
  13128.  
  13129.  
  13130.                                      Page 205
  13131.  
  13132.      Predefined Variables
  13133.  
  13134.  
  13135.             HOME                   Home directory (default is the
  13136.                                    initial current directory.)
  13137.  
  13138.             LSOPTIONS              Default set of command line
  13139.                                    options to be pasted ahead of any
  13140.                                    other command line options passed
  13141.                                    to ls.exe.
  13142.  
  13143.             MATCHFAIL  Bright Red  When filename or command
  13144.                                    completion doesn't match anything.
  13145.  
  13146.  
  13147.  
  13148.  
  13149.  
  13150.  
  13151.  
  13152.  
  13153.  
  13154.  
  13155.  
  13156.  
  13157.  
  13158.  
  13159.  
  13160.  
  13161.  
  13162.  
  13163.  
  13164.  
  13165.  
  13166.  
  13167.  
  13168.  
  13169.  
  13170.  
  13171.  
  13172.  
  13173.  
  13174.  
  13175.  
  13176.  
  13177.  
  13178.  
  13179.  
  13180.  
  13181.  
  13182.  
  13183.  
  13184.  
  13185.  
  13186.  
  13187.  
  13188.  
  13189.  
  13190.  
  13191.  
  13192.                                      Page 206
  13193.  
  13194.                                                          Predefined Variables
  13195.  
  13196.  
  13197.  
  13198.                        Environmental Variables Recognized
  13199.  
  13200.  
  13201.             Name          Default  Use                                  
  13202.  
  13203.             MIXEDCASEDRIVES        List of drives and UNC names for
  13204.                                    which ls.exe,  pwd.exe,
  13205.                                    wildcarding and the fullname and
  13206.                                    current directory functions should
  13207.                                    report filenames in mixed case
  13208.                                    rather than all lower case.
  13209.  
  13210.             MOREEOF         Green  End or Top of File in more.
  13211.  
  13212.             MOREERRORBright Yellow Unrecognizable command to more.
  13213.  
  13214.             MOREFILLIN      White  User response to more prompt.
  13215.  
  13216.             MOREPROMPT      Green  Prompt line in more.
  13217.  
  13218.             MORETOPMEMBright Yellow                                     
  13219.                                    Top of Memory message from more.
  13220.  
  13221.             NETWORKBUG             If NETWORKBUG = 1, the shell and
  13222.                                    all the utilities will read
  13223.                                    directory entries only one-at-a-
  13224.                                    time as a workaround for a
  13225.                                    networking bug.  (Not used on NT.)
  13226.  
  13227.             PATH                   Search path for executable files.
  13228.  
  13229.             PROMPT1    $@ $CDISK%  Primary command prompt template.
  13230.  
  13231.             PROMPT2    $@ $CDISK?  Continuation line prompt template.
  13232.  
  13233.             RADIX              16  Default radix used by more.exe and
  13234.                                    other utilities when displaying
  13235.                                    binary data.
  13236.  
  13237.             SHELL                  Always set to the pathname of the
  13238.                                    Hamilton C shell csh.exe file.
  13239.  
  13240.             SWITCHCHARS        -/  Characters that can be used as
  13241.                                    option introducers for the shell
  13242.                                    and utilities.
  13243.  
  13244.             SYSTEMDIRSBright Green Used by ls.exe for directories
  13245.                                    with the System bit on.
  13246.  
  13247.             SYSTEMFILES     Green  Used by ls.exe for files with the
  13248.                                    System bit on.
  13249.  
  13250.  
  13251.  
  13252.  
  13253.  
  13254.                                      Page 207
  13255.  
  13256.      Predefined Variables
  13257.  
  13258.  
  13259.             TABS                8  Used by more.exe, head.exe,
  13260.                                    tail.exe and tabs.exe to tell them
  13261.                                    how many character positions there
  13262.                                    are between tab stops.
  13263.  
  13264.             TAPE        \\.\tape0  Used by mt.exe under Windows NT to
  13265.                                    specify the pathname of the
  13266.                                    default tape drive.
  13267.  
  13268.  
  13269.  
  13270.  
  13271.  
  13272.  
  13273.  
  13274.  
  13275.  
  13276.  
  13277.  
  13278.  
  13279.  
  13280.  
  13281.  
  13282.  
  13283.  
  13284.  
  13285.  
  13286.  
  13287.  
  13288.  
  13289.  
  13290.  
  13291.  
  13292.  
  13293.  
  13294.  
  13295.  
  13296.  
  13297.  
  13298.  
  13299.  
  13300.  
  13301.  
  13302.  
  13303.  
  13304.  
  13305.  
  13306.  
  13307.  
  13308.  
  13309.  
  13310.  
  13311.  
  13312.  
  13313.  
  13314.  
  13315.  
  13316.                                      Page 208
  13317.  
  13318.                                                          Predefined Variables
  13319.  
  13320.  
  13321.  
  13322.                        Environmental Variables Recognized
  13323.  
  13324.  
  13325.             Name          Default  Use                                  
  13326.  
  13327.             TZ                     Used by tar.exe under OS/2 to tell
  13328.                                    it how to convert between local
  13329.                                    time and GMT.  (Under Windows NT,
  13330.                                    the system keeps track of the
  13331.                                    difference between local time and
  13332.                                    GMT, so the TZ variable is not
  13333.                                    needed.)  The TZ variable should
  13334.                                    be of the form of a three-letter
  13335.                                    timezone, e.g., EST, followed by a
  13336.                                    signed number giving the
  13337.                                    difference in hours between GMT
  13338.                                    and local time, followed by an
  13339.                                    optional daylight savings
  13340.                                    timezone.  Examples are EST5EDT in
  13341.                                    New York or PST8PDT in California.
  13342.  
  13343.  
  13344.                  Environmental variables  are  passed  to  any  child
  13345.                  processes or  screens  you  create  by  invoking  an
  13346.                  external utility  or application.   When  Hamilton C
  13347.                  shell starts  up it looks for the ones shown here to
  13348.                  be defined  in the  environment it  inherits.  HOME,
  13349.                  PATH and  SHELL  are special: if they're not already
  13350.                  defined, then the shell creates them.
  13351.  
  13352.                  On Windows NT, environmental variables are not case-
  13353.                  sensitive, so, e.g., Path and PATH refer to the same
  13354.                  thing.
  13355.  
  13356.  
  13357.  
  13358.  
  13359.  
  13360.  
  13361.  
  13362.  
  13363.  
  13364.  
  13365.  
  13366.  
  13367.  
  13368.  
  13369.  
  13370.  
  13371.  
  13372.  
  13373.  
  13374.  
  13375.  
  13376.  
  13377.  
  13378.                                      Page 209
  13379.  
  13380.      Predefined Variables
  13381.  
  13382.  
  13383.             
  13384.             
  13385.  
  13386.  
  13387.                         Predefined Process-Wide Variables
  13388.  
  13389.  
  13390.             Name          Default  Use                                  
  13391.  
  13392.             $                      A synonym for the processid
  13393.                                    variable.
  13394.  
  13395.             bsdhistory          0  By default, ``!!'' is the
  13396.                                    immediately preceding command and
  13397.                                    ``!-1'' is the one before that.
  13398.                                    Setting bsdhistory = 1 makes them
  13399.                                    the same.
  13400.  
  13401.             cdpath           null  Same as the CDPATH environmental
  13402.                                    variable, broken into words.
  13403.  
  13404.             escapesym           ^  Character to be interpreted as a
  13405.                                    literal escape character.
  13406.  
  13407.             histchars          !%  Characters which introduce long-
  13408.                                    form and short-form history
  13409.                                    references, respectively.
  13410.  
  13411.             home                   Same as the HOME environmental
  13412.                                    variable.
  13413.  
  13414.             NTVersion              Build number of the NT system on
  13415.                                    which the shell is running, e.g.,
  13416.                                    340 for the October Beta.  (Not
  13417.                                    defined on OS/2.)
  13418.  
  13419.             os2version             Version number of the OS/2 system
  13420.                                    on which the shell is running.
  13421.                                    (Not defined on NT.)
  13422.  
  13423.             path                   Same as the PATH environmental
  13424.                                    variable, broken into words.
  13425.  
  13426.             processid              The unique process ID assigned by
  13427.                                    the OS/2 or NT kernel to this copy
  13428.                                    of the C shell.
  13429.  
  13430.             prompt1    $@ $CDISK%  Same as PROMPT1 environmental
  13431.                                    variable.
  13432.  
  13433.             prompt2    $@ $CDISK?  Same as PROMPT2 environmental
  13434.                                    variable.
  13435.  
  13436.  
  13437.  
  13438.  
  13439.  
  13440.                                      Page 210
  13441.  
  13442.                                                          Predefined Variables
  13443.  
  13444.  
  13445.             savehist            0  Save the history contents into
  13446.                                    history.csh in the home directory.
  13447.  
  13448.             shell                  Same as SHELL environmental
  13449.                                    variable.
  13450.  
  13451.             WinVersion             Version number of the Windows API
  13452.                                    on which the shell is running,
  13453.                                    e.g., 3.1 for the October Beta.
  13454.                                    (Not defined on OS/2.)
  13455.  
  13456.  
  13457.                  Any user-defined  variables (with  the exception  of
  13458.                  the  parameter   names  of   a  procedure  or  those
  13459.                  variables explicitly  defined as  local) are  shared
  13460.                  globally by all threads.
  13461.  
  13462.  
  13463.  
  13464.  
  13465.  
  13466.  
  13467.  
  13468.  
  13469.  
  13470.  
  13471.  
  13472.  
  13473.  
  13474.  
  13475.  
  13476.  
  13477.  
  13478.  
  13479.  
  13480.  
  13481.  
  13482.  
  13483.  
  13484.  
  13485.  
  13486.  
  13487.  
  13488.  
  13489.  
  13490.  
  13491.  
  13492.  
  13493.  
  13494.  
  13495.  
  13496.  
  13497.  
  13498.  
  13499.  
  13500.  
  13501.  
  13502.                                      Page 211
  13503.  
  13504.      Predefined Variables
  13505.  
  13506.  
  13507.             
  13508.  
  13509.  
  13510.                          Predefined Per-Thread Variables
  13511.  
  13512.  
  13513.             Inherited from the parent thread:
  13514.  
  13515.             Name          Default  Use                                  
  13516.  
  13517.             argv                   Any argument words passed to the
  13518.                                    shell or to a .csh batch file.
  13519.  
  13520.             bsdargv             0  If set, $argv[0] contains the name
  13521.                                    of the script, just as it would
  13522.                                    under the original Berkeley C
  13523.                                    shell; by default, $argv[0] is the
  13524.                                    first argument word.
  13525.  
  13526.             cdhome              0  If set, ``cd'' with no argument is
  13527.                                    the same as ``cd $home''; default
  13528.                                    is to simply print the current
  13529.                                    directory name.
  13530.  
  13531.             cdisk                  Current disk, not including colon.
  13532.  
  13533.             CDISK                  Same as cdisk, but in upper case.
  13534.  
  13535.             chgdisk             0  If set, cd automatically does a
  13536.                                    DosSelectDisk if the path is on
  13537.                                    another disk.
  13538.  
  13539.             cwd                    Full pathname of the current
  13540.                                    directory.
  13541.  
  13542.             gotowindow         50  Number of statements a goto can
  13543.                                    jump over (when not inside a
  13544.                                    nested block) without being
  13545.                                    considered an error.
  13546.  
  13547.             nohashing           0  Determine how/whether path hashing
  13548.                                    is done:  0 means full path
  13549.                                    hashing of the directories on the
  13550.                                    search path; 1 means turn off
  13551.                                    hashing completely; 2 means hash
  13552.                                    only the directories which do not
  13553.                                    depend on the setting of the
  13554.                                    current directory.
  13555.  
  13556.             noclobber           0  If True, don't allow redirection
  13557.                                    to overwrite an existing file
  13558.                                    unless the ``!'' override is
  13559.                                    given.
  13560.  
  13561.  
  13562.  
  13563.  
  13564.                                      Page 212
  13565.  
  13566.                                                          Predefined Variables
  13567.  
  13568.  
  13569.             noglob                 A synonym for the nowild variable.
  13570.  
  13571.             nonohidden          0  Determine whether wildcarding will
  13572.                                    match against hidden files:  0
  13573.                                    means don't match hidden files; 1
  13574.                                    means hidden files will be found.
  13575.  
  13576.             nonomatch           0  Determine the response to a
  13577.                                    wildcard that doesn't match
  13578.                                    anything:  0 means it's an error;
  13579.                                    1 means pass it through to the
  13580.                                    application; 2 means simply
  13581.                                    discard it.
  13582.  
  13583.  
  13584.  
  13585.  
  13586.  
  13587.  
  13588.  
  13589.  
  13590.  
  13591.  
  13592.  
  13593.  
  13594.  
  13595.  
  13596.  
  13597.  
  13598.  
  13599.  
  13600.  
  13601.  
  13602.  
  13603.  
  13604.  
  13605.  
  13606.  
  13607.  
  13608.  
  13609.  
  13610.  
  13611.  
  13612.  
  13613.  
  13614.  
  13615.  
  13616.  
  13617.  
  13618.  
  13619.  
  13620.  
  13621.  
  13622.  
  13623.  
  13624.  
  13625.  
  13626.                                      Page 213
  13627.  
  13628.      Predefined Variables
  13629.  
  13630.  
  13631.             
  13632.  
  13633.  
  13634.                          Predefined Per-Thread Variables
  13635.  
  13636.  
  13637.             Inherited from the parent thread:
  13638.  
  13639.             Name          Default  Use                                  
  13640.  
  13641.             nonovar             0  Determine the response to a
  13642.                                    reference to a non-existent
  13643.                                    variable, procedure or alias.
  13644.                                    Same encoding as nonomatch.
  13645.  
  13646.             nowild              0  If True, turn off filename
  13647.                                    wildcarding.
  13648.  
  13649.             nullwords           0  Determines whether an array index
  13650.                                    off the end of a list is an error
  13651.                                    (0) or returns a null word (1).
  13652.  
  13653.             precision           6  Number of decimal places to print
  13654.                                    when displaying floating point
  13655.                                    values.
  13656.  
  13657.             tailstatus          0  Determines whether the status
  13658.                                    variable will reflect the reflect
  13659.                                    the return code from the leftmost
  13660.                                    or rightmost stage of a pipeline:
  13661.                                    0 means leftmost; 1 means
  13662.                                    rightmost.
  13663.  
  13664.             verbose             0  If True, print out all available
  13665.                                    information when reporting errors.
  13666.  
  13667.  
  13668.                  Each new  thread is  initialized  with  default  on-
  13669.                  interrupt  processing  (a  forced  exit),  and  null
  13670.                  search and replace strings.  echoinput, ignoreerrors
  13671.                  and interactive  are initialized for the main thread
  13672.                  based on command-line options.
  13673.  
  13674.                  Each thread  also has  its own independent notion of
  13675.                  current  disk  and  current  directories,  initially
  13676.                  inherited from its parent.
  13677.  
  13678.  
  13679.  
  13680.  
  13681.  
  13682.  
  13683.  
  13684.  
  13685.  
  13686.  
  13687.  
  13688.                                      Page 214
  13689.  
  13690.                                                          Predefined Variables
  13691.  
  13692.  
  13693.  
  13694.                          Predefined Per-Thread Variables
  13695.  
  13696.  
  13697.             Always initialized  to the  default for  each  new  child
  13698.             thread:
  13699.  
  13700.             Name          Default  Use                                  
  13701.  
  13702.             *                      A synonym for the argv variable.
  13703.  
  13704.             <                      A synonym for the getline
  13705.                                    variable.
  13706.  
  13707.             @                      A synonym for the stmtnumber
  13708.                                    variable.
  13709.  
  13710.             child               0  Identification number of the last
  13711.                                    child process spawned.
  13712.  
  13713.             echoinput           0  Copy the input to stdout as it's
  13714.                                    read.
  13715.  
  13716.             eofgetline          0  Pseudo-variable to indicate if the
  13717.                                    last reference to getline
  13718.                                    encountered an end-of-file
  13719.                                    condition.
  13720.  
  13721.             getchar                Read one character from stdin
  13722.                                    without echoing.  If stdin is tied
  13723.                                    to the keyboard, outboard keys are
  13724.                                    returned as a two-character
  13725.                                    string.
  13726.  
  13727.             getline                Read one line from stdin pseudo-
  13728.                                    variable.  If stdin is tied to the
  13729.                                    keyboard, keystrokes are echoed as
  13730.                                    they're typed.
  13731.  
  13732.             history             0  Number of statements to remember
  13733.                                    on the history list; 0 turns off
  13734.                                    the history mechanism.  (If the
  13735.                                    thread is interactive, history is
  13736.                                    automatically set to 100.)
  13737.  
  13738.             ignoreeof           0  If True, don't exit at EOF on
  13739.                                    stdin; insist on an exit command.
  13740.  
  13741.             ignoreerrors        0  Determine whether execution should
  13742.                                    continue if an error occurs:  0
  13743.                                    means the thread exits; 1 (the
  13744.                                    default for an interactive thread)
  13745.                                    means exit from loops or
  13746.                                    procedures and try to read a new
  13747.  
  13748.  
  13749.  
  13750.                                      Page 215
  13751.  
  13752.      Predefined Variables
  13753.  
  13754.  
  13755.                                    command; 2 means ignore all
  13756.                                    errors.
  13757.  
  13758.             ignorestatus        1  If True, a non-zero status code
  13759.                                    from a child process is ignored.
  13760.                                    Otherwise, it's an error.
  13761.  
  13762.             interactive         0  If True, prompt for input.
  13763.  
  13764.             irqmask             0  Determines whether interrupts are
  13765.                                    enabled (0), deferred until the
  13766.                                    mask is cleared again (1) or
  13767.                                    ignored (2).
  13768.  
  13769.             scriptname             Name of the C shell script file
  13770.                                    being executed, if any.
  13771.  
  13772.  
  13773.  
  13774.  
  13775.  
  13776.  
  13777.  
  13778.  
  13779.  
  13780.  
  13781.  
  13782.  
  13783.  
  13784.  
  13785.  
  13786.  
  13787.  
  13788.  
  13789.  
  13790.  
  13791.  
  13792.  
  13793.  
  13794.  
  13795.  
  13796.  
  13797.  
  13798.  
  13799.  
  13800.  
  13801.  
  13802.  
  13803.  
  13804.  
  13805.  
  13806.  
  13807.  
  13808.  
  13809.  
  13810.  
  13811.  
  13812.                                      Page 216
  13813.  
  13814.                                                          Predefined Variables
  13815.  
  13816.  
  13817.  
  13818.                          Predefined Per-Thread Variables
  13819.  
  13820.  
  13821.             Always initialized  to the  default for  each  new  child
  13822.             thread:
  13823.  
  13824.             Name          Default  Use                                  
  13825.  
  13826.             status              0  Exit code of the last child
  13827.                                    process.
  13828.  
  13829.             stmtnumber          1  Autoincremented statement number
  13830.                                    used with the history list and in
  13831.                                    prompting.
  13832.  
  13833.             threadid               Thread id of the currently
  13834.                                    executing thread.
  13835.  
  13836.  
  13837.  
  13838.  
  13839.  
  13840.  
  13841.  
  13842.  
  13843.  
  13844.  
  13845.  
  13846.  
  13847.  
  13848.  
  13849.  
  13850.  
  13851.  
  13852.  
  13853.  
  13854.  
  13855.  
  13856.  
  13857.  
  13858.  
  13859.  
  13860.  
  13861.  
  13862.  
  13863.  
  13864.  
  13865.  
  13866.  
  13867.  
  13868.  
  13869.  
  13870.  
  13871.  
  13872.  
  13873.  
  13874.                                      Page 217
  13875.  
  13876.      Predefined Variables
  13877.  
  13878.  
  13879.  
  13880.                               Predefined Variables
  13881.  
  13882.                                  Sorted by Name
  13883.  
  13884.  
  13885.             Legend for this table:
  13886.  
  13887.               COURIER A setenv environmental variable.  Environmental
  13888.                       variables are  passed to any child processes or
  13889.                       screens you  create  by  invoking  an  external
  13890.                       utility or  application.  When Hamilton C shell
  13891.                       starts up  it looks  for the ones shown here to
  13892.                       be defined  in the  environment it inherits; if
  13893.                       they're not  already defined, the shell creates
  13894.                       them.
  13895.  
  13896.               bold    A set  variable shared  by all threads:  if one
  13897.                       makes a change, all will see it.
  13898.  
  13899.               normal  Each thread  gets its  own copy but the initial
  13900.                       value is inherited from its parent.
  13901.  
  13902.               italics Each  thread   gets  its   own  copy   but  the
  13903.                       initialization is always to a defined value.
  13904.  
  13905.             Name          Default  Use                                  
  13906.  
  13907.             $                      A synonym for the processid
  13908.                                    variable.
  13909.  
  13910.             *                      A synonym for the argv variable.
  13911.  
  13912.             <                      A synonym for the getline
  13913.                                    variable.
  13914.  
  13915.             @                      A synonym for the stmtnumber
  13916.                                    variable.
  13917.  
  13918.             ADDITIONSBright Green  Lines added found by diff.
  13919.  
  13920.             argv                   Any argument words passed to the
  13921.                                    shell or to a .csh batch file.
  13922.  
  13923.             bsdargv             0  If set, $argv[0] contains the name
  13924.                                    of the script, just as it would
  13925.                                    under the original Berkeley C
  13926.                                    shell; by default, $argv[0] is the
  13927.                                    first argument word.
  13928.  
  13929.             bsdhistory          0  By default, ``!!'' is the
  13930.                                    immediately preceding command and
  13931.                                    ``!-1'' is the one before that.
  13932.  
  13933.  
  13934.  
  13935.  
  13936.                                      Page 218
  13937.  
  13938.                                                          Predefined Variables
  13939.  
  13940.  
  13941.                                    Setting bsdhistory = 1 makes them
  13942.                                    the same.
  13943.  
  13944.             cdhome              0  If set, ``cd'' with no argument is
  13945.                                    the same as ``cd $home''; default
  13946.                                    is to simply print the current
  13947.                                    directory name.
  13948.  
  13949.             cdisk                  Current disk, not including colon.
  13950.  
  13951.             CDISK                  Same as cdisk, but in upper case.
  13952.  
  13953.             CDPATH                 List of directories to search for
  13954.                                    the subdirectory specified as the
  13955.                                    new current directory.
  13956.  
  13957.  
  13958.  
  13959.  
  13960.  
  13961.  
  13962.  
  13963.  
  13964.  
  13965.  
  13966.  
  13967.  
  13968.  
  13969.  
  13970.  
  13971.  
  13972.  
  13973.  
  13974.  
  13975.  
  13976.  
  13977.  
  13978.  
  13979.  
  13980.  
  13981.  
  13982.  
  13983.  
  13984.  
  13985.  
  13986.  
  13987.  
  13988.  
  13989.  
  13990.  
  13991.  
  13992.  
  13993.  
  13994.  
  13995.  
  13996.  
  13997.  
  13998.                                      Page 219
  13999.  
  14000.      Predefined Variables
  14001.  
  14002.  
  14003.  
  14004.                               Predefined Variables
  14005.  
  14006.                                  Sorted by Name
  14007.  
  14008.  
  14009.             Name          Default  Use                                  
  14010.  
  14011.             cdpath           null  Same as the CDPATH environmental
  14012.                                    variable, broken into words.
  14013.  
  14014.             chgdisk             0  If set, cd automatically does a
  14015.                                    DosSelectDisk if the path is on
  14016.                                    another disk.
  14017.  
  14018.             child               0  Identification number of the last
  14019.                                    child process spawned.
  14020.  
  14021.             COLORS White on Black  Normal screen colors.
  14022.  
  14023.             COMSPEC                Usually, this is the pathname of
  14024.                                    cmd.exe.  If you set it to point
  14025.                                    to the C shell, e.g., so other
  14026.                                    programs will invoke the C shell
  14027.                                    rather than cmd.exe, the C shell
  14028.                                    will try to look through the
  14029.                                    search path for cmd.exe if it
  14030.                                    needs to run a .cmd file.
  14031.  
  14032.             CSHOPTIONS             Default set of command line
  14033.                                    options to be pasted ahead of any
  14034.                                    other command line options passed
  14035.                                    to csh.exe.
  14036.  
  14037.             cwd                    Full pathname of the current
  14038.                                    directory.
  14039.  
  14040.             DELETIONS  Bright Red  Lines deleted found by diff.
  14041.  
  14042.             DIRECTORIES    Bright  Directories listed by ls.
  14043.  
  14044.             DUPLICATES      Green  When filename completion matches
  14045.                                    matches more than one name.
  14046.  
  14047.             DRIVEMASK              Used by du.exe, pwd.exe and vl.exe
  14048.                                    to limit the default list of
  14049.                                    drives it will report on.  Written
  14050.                                    as a list of alphabetic characters
  14051.                                    representing the drives you want
  14052.                                    listed; ranges are allowed.  If
  14053.                                    you don't define this variable,
  14054.                                    all drives beginning with C: are
  14055.                                    normally reported.
  14056.  
  14057.  
  14058.  
  14059.  
  14060.                                      Page 220
  14061.  
  14062.                                                          Predefined Variables
  14063.  
  14064.  
  14065.             echoinput           0  Copy the input to stdout as it's
  14066.                                    read.
  14067.  
  14068.             eofgetline          0  Pseudo-variable to indicate if the
  14069.                                    last reference to getline
  14070.                                    encountered an end-of-file
  14071.                                    condition.
  14072.  
  14073.             ESCAPESYM           ^  Character to be interpreted as a
  14074.                                    literal escape character.  Placed
  14075.                                    in the environment only if it is
  14076.                                    not the default circumflex.
  14077.  
  14078.  
  14079.  
  14080.  
  14081.  
  14082.  
  14083.  
  14084.  
  14085.  
  14086.  
  14087.  
  14088.  
  14089.  
  14090.  
  14091.  
  14092.  
  14093.  
  14094.  
  14095.  
  14096.  
  14097.  
  14098.  
  14099.  
  14100.  
  14101.  
  14102.  
  14103.  
  14104.  
  14105.  
  14106.  
  14107.  
  14108.  
  14109.  
  14110.  
  14111.  
  14112.  
  14113.  
  14114.  
  14115.  
  14116.  
  14117.  
  14118.  
  14119.  
  14120.  
  14121.  
  14122.                                      Page 221
  14123.  
  14124.      Predefined Variables
  14125.  
  14126.  
  14127.  
  14128.                               Predefined Variables
  14129.  
  14130.                                  Sorted by Name
  14131.  
  14132.  
  14133.             Name          Default  Use                                  
  14134.  
  14135.             escapesym           ^  Same as the ESCAPESYM
  14136.                                    environmental variable.
  14137.  
  14138.             FOREIGNFILESBright Red Filetypes in a tar file that have
  14139.                                    no counterpart on OS/2 or NT.
  14140.  
  14141.             getchar                Read one character from stdin
  14142.                                    without echoing.  If stdin is tied
  14143.                                    to the keyboard, outboard keys are
  14144.                                    returned as a two-character
  14145.                                    string.
  14146.  
  14147.             getline                Read one line from stdin pseudo-
  14148.                                    variable.  If stdin is tied to the
  14149.                                    keyboard, keystrokes are echoed as
  14150.                                    they're typed.
  14151.  
  14152.             gotowindow         50  Number of statements a goto can
  14153.                                    jump over (when not inside a
  14154.                                    nested block) without being
  14155.                                    considered an error.
  14156.  
  14157.             HIGHLIGHT      Bright  Current disk or directory.
  14158.  
  14159.             histchars          !%  Characters which introduce long-
  14160.                                    form and short-form history
  14161.                                    references, respectively.
  14162.  
  14163.             history             0  Number of statements to remember
  14164.                                    on the history list; 0 turns off
  14165.                                    the history mechanism.  (If the
  14166.                                    thread is interactive, history is
  14167.                                    automatically set to 100.)
  14168.  
  14169.             HOME                   Home directory (default is the
  14170.                                    initial current directory.)
  14171.  
  14172.             home                   Same as the HOME environmental
  14173.                                    variable.
  14174.  
  14175.             ignoreeof           0  If True, don't exit at EOF on
  14176.                                    stdin; insist on an exit command.
  14177.  
  14178.             ignoreerrors        0  Determine whether execution should
  14179.                                    continue if an error occurs:  0
  14180.                                    means the thread exits; 1 (the
  14181.  
  14182.  
  14183.  
  14184.                                      Page 222
  14185.  
  14186.                                                          Predefined Variables
  14187.  
  14188.  
  14189.                                    default for an interactive thread)
  14190.                                    means exit from loops or
  14191.                                    procedures and try to read a new
  14192.                                    command; 2 means ignore all
  14193.                                    errors.
  14194.  
  14195.             ignorestatus        1  If True, a non-zero status code
  14196.                                    from a child process is ignored.
  14197.                                    Otherwise, it's an error.
  14198.  
  14199.             interactive         0  If True, prompt for input.
  14200.  
  14201.  
  14202.  
  14203.  
  14204.  
  14205.  
  14206.  
  14207.  
  14208.  
  14209.  
  14210.  
  14211.  
  14212.  
  14213.  
  14214.  
  14215.  
  14216.  
  14217.  
  14218.  
  14219.  
  14220.  
  14221.  
  14222.  
  14223.  
  14224.  
  14225.  
  14226.  
  14227.  
  14228.  
  14229.  
  14230.  
  14231.  
  14232.  
  14233.  
  14234.  
  14235.  
  14236.  
  14237.  
  14238.  
  14239.  
  14240.  
  14241.  
  14242.  
  14243.  
  14244.  
  14245.  
  14246.                                      Page 223
  14247.  
  14248.      Predefined Variables
  14249.  
  14250.  
  14251.  
  14252.                               Predefined Variables
  14253.  
  14254.                                  Sorted by Name
  14255.  
  14256.  
  14257.             Name          Default  Use                                  
  14258.  
  14259.             irqmask             0  Determines whether interrupts are
  14260.                                    enabled (0), deferred until the
  14261.                                    mask is cleared again (1) or
  14262.                                    ignored (2).
  14263.  
  14264.             LSOPTIONS              Default set of command line
  14265.                                    options to be pasted ahead of any
  14266.                                    other command line options passed
  14267.                                    to ls.exe.
  14268.  
  14269.             MATCHFAIL  Bright Red  When filename or command
  14270.                                    completion doesn't match anything.
  14271.  
  14272.             MIXEDCASEDRIVES        List of drives and UNC names for
  14273.                                    which ls.exe,  pwd.exe,
  14274.                                    wildcarding and the fullname and
  14275.                                    current directory functions
  14276.                                    should report filenames in mixed
  14277.                                    case rather than all lower case.
  14278.  
  14279.             MOREEOF         Green  End or Top of File in more.
  14280.  
  14281.             MOREERRORBright Yellow Unrecognizable command to more.
  14282.  
  14283.             MOREFILLIN      White  User response to more prompt.
  14284.  
  14285.             MOREPROMPT      Green  Prompt line in more.
  14286.  
  14287.             MORETOPMEMBright Yellow                                     
  14288.                                    Top of Memory message from more.
  14289.  
  14290.             NETWORKBUG             If NETWORKBUG = 1, the shell and
  14291.                                    all the utilities will read
  14292.                                    directory entries only one-at-a-
  14293.                                    time as a workaround for a
  14294.                                    networking bug.  (Not used on NT.)
  14295.  
  14296.             nohashing           0  Determine how/whether path hashing
  14297.                                    is done:  0 means full path
  14298.                                    hashing of the directories on the
  14299.                                    search path; 1 means turn off
  14300.                                    hashing completely; 2 means hash
  14301.                                    only the directories which do not
  14302.                                    depend on the setting of the
  14303.                                    current directory.
  14304.  
  14305.  
  14306.  
  14307.  
  14308.                                      Page 224
  14309.  
  14310.                                                          Predefined Variables
  14311.  
  14312.  
  14313.             noclobber           0  If True, don't allow redirection
  14314.                                    to overwrite an existing file
  14315.                                    unless the ``!'' override is
  14316.                                    given.
  14317.  
  14318.             noglob                 A synonym for the nowild variable.
  14319.  
  14320.             nonohidden          0  Determine whether wildcarding will
  14321.                                    match against hidden files:  0
  14322.                                    means don't match hidden files; 1
  14323.                                    means hidden files will be found.
  14324.  
  14325.  
  14326.  
  14327.  
  14328.  
  14329.  
  14330.  
  14331.  
  14332.  
  14333.  
  14334.  
  14335.  
  14336.  
  14337.  
  14338.  
  14339.  
  14340.  
  14341.  
  14342.  
  14343.  
  14344.  
  14345.  
  14346.  
  14347.  
  14348.  
  14349.  
  14350.  
  14351.  
  14352.  
  14353.  
  14354.  
  14355.  
  14356.  
  14357.  
  14358.  
  14359.  
  14360.  
  14361.  
  14362.  
  14363.  
  14364.  
  14365.  
  14366.  
  14367.  
  14368.  
  14369.  
  14370.                                      Page 225
  14371.  
  14372.      Predefined Variables
  14373.  
  14374.  
  14375.  
  14376.                               Predefined Variables
  14377.  
  14378.                                  Sorted by Name
  14379.  
  14380.  
  14381.             Name          Default  Use                                  
  14382.  
  14383.             nonomatch           0  Determine the response to a
  14384.                                    wildcard that doesn't match
  14385.                                    anything:  0 means it's an error;
  14386.                                    1 means pass it through to the
  14387.                                    application; 2 means simply
  14388.                                    discard it.
  14389.  
  14390.             nonovar             0  Determine the response to a non-
  14391.                                    existent variable, procedure or
  14392.                                    alias.  Same encoding as
  14393.                                    nonomatch.
  14394.  
  14395.             nowild              0  If True, turn off filename
  14396.                                    wildcarding.
  14397.  
  14398.             NTVersion              Build number of the NT system on
  14399.                                    which the shell is running, e.g.,
  14400.                                    340 for the October Beta.  (Not
  14401.                                    defined on OS/2.)
  14402.  
  14403.             nullwords           0  Determines whether an array index
  14404.                                    off the end of a list is an error
  14405.                                    (0) or returns a null word (1).
  14406.  
  14407.             os2version             Version number of the OS/2 system
  14408.                                    on which the shell is running.
  14409.                                    (Not defined on NT.)
  14410.  
  14411.             PATH                   Search path for executable files.
  14412.  
  14413.             path                   Same as the PATH environmental
  14414.                                    variable, broken into words.
  14415.  
  14416.             precision           6  Number of decimal places to print
  14417.                                    when displaying floating point
  14418.                                    values.
  14419.  
  14420.             processid              The unique process ID assigned by
  14421.                                    the OS/2 or NT kernel to this copy
  14422.                                    of the C shell.
  14423.  
  14424.             PROMPT1    $@ $CDISK%  Primary command prompt template.
  14425.  
  14426.             prompt1                Same as the PROMPT1 environmental
  14427.                                    variable.
  14428.  
  14429.  
  14430.  
  14431.  
  14432.                                      Page 226
  14433.  
  14434.                                                          Predefined Variables
  14435.  
  14436.  
  14437.             PROMPT2    $@ $CDISK?  Continuation line prompt template.
  14438.  
  14439.             prompt2                Same as the PROMPT2 environmental
  14440.                                    variable.
  14441.  
  14442.             RADIX              16  Default radix used by more.exe
  14443.                                    when displaying binary data.
  14444.  
  14445.             savehist            0  Save the history contents into
  14446.                                    history.csh in the home directory.
  14447.  
  14448.             scriptname             Name of the C shell script file
  14449.                                    being executed, if any.
  14450.  
  14451.             SHELL                  Always set to the pathname of the
  14452.                                    Hamilton C shell csh.exe file.
  14453.  
  14454.  
  14455.  
  14456.  
  14457.  
  14458.  
  14459.  
  14460.  
  14461.  
  14462.  
  14463.  
  14464.  
  14465.  
  14466.  
  14467.  
  14468.  
  14469.  
  14470.  
  14471.  
  14472.  
  14473.  
  14474.  
  14475.  
  14476.  
  14477.  
  14478.  
  14479.  
  14480.  
  14481.  
  14482.  
  14483.  
  14484.  
  14485.  
  14486.  
  14487.  
  14488.  
  14489.  
  14490.  
  14491.  
  14492.  
  14493.  
  14494.                                      Page 227
  14495.  
  14496.      Predefined Variables
  14497.  
  14498.  
  14499.  
  14500.                               Predefined Variables
  14501.  
  14502.                                  Sorted by Name
  14503.  
  14504.  
  14505.             Name          Default  Use                                  
  14506.  
  14507.             shell                  Same as the SHELL environmental
  14508.                                    variable.
  14509.  
  14510.             status              0  Exit code of the last child
  14511.                                    process.
  14512.  
  14513.             stmtnumber          1  Autoincremented statement number
  14514.                                    used with the history list and in
  14515.                                    prompting.
  14516.  
  14517.             SWITCHCHARS        -/  Characters that can be used as
  14518.                                    option introducers for the shell
  14519.                                    and utilities.
  14520.  
  14521.             SYSTEMDIRSBright Green Used by ls.exe for directories
  14522.                                    with the System bit on.
  14523.  
  14524.             SYSTEMFILES     Green  Used by ls.exe for files with the
  14525.                                    System bit on.
  14526.  
  14527.             TABS                8  Used by more.exe to tell it how
  14528.                                    many character positions there are
  14529.                                    between tab stops.
  14530.  
  14531.             tailstatus          0  Determines whether the status
  14532.                                    variable will reflect the reflect
  14533.                                    the return code from the leftmost
  14534.                                    or rightmost stage of a pipeline:
  14535.                                    0 means leftmost; 1 means
  14536.                                    rightmost.
  14537.  
  14538.             TAPE        \\.\tape0  Used by mt.exe under Windows NT to
  14539.                                    specify the pathname of the
  14540.                                    default tape drive.
  14541.  
  14542.             threadid               Thread id of the currently
  14543.                                    executing thread.
  14544.  
  14545.             TZ                     Used by tar.exe under OS/2 to tell
  14546.                                    it how to convert between local
  14547.                                    time and GMT.  (Under Windows NT,
  14548.                                    the system keeps track of the
  14549.                                    difference between local time and
  14550.                                    GMT, so the TZ variable is not
  14551.                                    needed.)  The TZ variable should
  14552.                                    be in the form of a three-letter
  14553.  
  14554.  
  14555.  
  14556.                                      Page 228
  14557.  
  14558.                                                          Predefined Variables
  14559.  
  14560.  
  14561.                                    timezone, e.g., EST, followed by a
  14562.                                    signed number giving the
  14563.                                    difference in hours between GMT
  14564.                                    and local time, followed by an
  14565.                                    optional daylight savings
  14566.                                    timezone.  Examples are EST5EDT in
  14567.                                    New York or PST8PDT in California.
  14568.  
  14569.             verbose             0  If True, print out all available
  14570.                                    information when reporting errors.
  14571.  
  14572.             WinVersion             Version number of the Windows API
  14573.                                    on which the shell is running,
  14574.                                    e.g., 3.1 for the October Beta.
  14575.                                    (Not defined on OS/2.)
  14576.  
  14577.  
  14578.  
  14579.  
  14580.  
  14581.  
  14582.  
  14583.  
  14584.  
  14585.  
  14586.  
  14587.  
  14588.  
  14589.  
  14590.  
  14591.  
  14592.  
  14593.  
  14594.  
  14595.  
  14596.  
  14597.  
  14598.  
  14599.  
  14600.  
  14601.  
  14602.  
  14603.  
  14604.  
  14605.  
  14606.  
  14607.  
  14608.  
  14609.  
  14610.  
  14611.  
  14612.  
  14613.  
  14614.  
  14615.  
  14616.  
  14617.  
  14618.                                      Page 229
  14619.  
  14620.      Built-in Procedures
  14621.  
  14622.  
  14623.  
  14624.                                         
  14625.  
  14626.  
  14627.  
  14628.  
  14629.                                Built-in Procedures
  14630.  
  14631.  
  14632.               Name                        Function                   
  14633.  
  14634.  
  14635.             Filename Functions:
  14636.  
  14637.               childpath(p, c)             Test whether filename c
  14638.                                           could be in a subdirectory
  14639.                                           of p.  (Does not test for
  14640.                                           actual existence of either
  14641.                                           c or p.)
  14642.  
  14643.               driveno(p)                  Drive number implied by
  14644.                                           pathname p.
  14645.  
  14646.               fullpath(p)                 Fully resolve pathname p.
  14647.  
  14648.               samepath(a, b)              Test whether two filenames,
  14649.                                           a and b, point to the same
  14650.                                           file.
  14651.  
  14652.  
  14653.             Math Functions:
  14654.  
  14655.               abs(x)                      Absolute value
  14656.  
  14657.               acos(x)   asin(x)   atan(x)   cos(x)   sin(x)   tan(x)
  14658.                                           Trigonometric functions
  14659.  
  14660.               cosh(x)   sinh(x)   tanh(x) Hyperbolic functions
  14661.  
  14662.               ceil(x)                     Ceiling (lowest integer |
  14663.                                           x)
  14664.  
  14665.               exp(x)   log(x)   log2(x)   log10(x)  Exponential and
  14666.                                           logarithmic functions
  14667.  
  14668.               floor(x)                    Floor (highest integer ú x)
  14669.  
  14670.               round(x)                    floor(x + 0.5)
  14671.  
  14672.               sqrt(x)                     Square root
  14673.  
  14674.  
  14675.  
  14676.  
  14677.  
  14678.  
  14679.  
  14680.                                      Page 230
  14681.  
  14682.                                                           Built-in Procedures
  14683.  
  14684.  
  14685.  
  14686.                                Built-in Procedures
  14687.  
  14688.  
  14689.               Name                        Function                   
  14690.  
  14691.  
  14692.             String Functions:
  14693.  
  14694.               ansi(color)                 Return an ANSI escape
  14695.                                           sequence which will produce
  14696.                                           the specified screen
  14697.                                           colors.  If the argument is
  14698.                                           ambiguous, e.g., simply
  14699.                                           ``bright,'' it's taken as a
  14700.                                           modification of the default
  14701.                                           colors specified by the
  14702.                                           COLORS variable.
  14703.  
  14704.               char(i)                     Return the character
  14705.                                           corresponding to the
  14706.                                           numeric value i.
  14707.  
  14708.               code(c)                     Return the numeric encoding
  14709.                                           of the character c.
  14710.  
  14711.               concat(a, b, ...)           Concatenation of a series
  14712.                                           of strings.
  14713.  
  14714.               isinteger(x)                Test whether x is an
  14715.                                           integer.  (Remember that
  14716.                                           null strings and strings
  14717.                                           consisting only of white
  14718.                                           space are considered equal
  14719.                                           to 0.)
  14720.  
  14721.               isnumber(x)                 Test whether x is a number.
  14722.  
  14723.               printf(fmt, ...)            Perform C language-style
  14724.                                           print formatting, returning
  14725.                                           the result as a string.
  14726.                                           (See table of format
  14727.                                           conversions on following
  14728.                                           page.)
  14729.  
  14730.               reverse(s)                  Reverse the order of
  14731.                                           characters in s.
  14732.  
  14733.               strindex(a, b)              Return the position in a of
  14734.                                           the first occurrence of b.
  14735.                                           (0 means b was not found.)
  14736.  
  14737.               strlen(s)                   Number of characters in s,
  14738.                                           represented as a string
  14739.  
  14740.  
  14741.  
  14742.                                      Page 231
  14743.  
  14744.      Built-in Procedures
  14745.  
  14746.  
  14747.               substr(s, b, i)             Substring of length i
  14748.                                           beginning at b-th character
  14749.                                           of s.  (i = 0 means ``rest
  14750.                                           of s'')
  14751.  
  14752.               upper(s)   lower(s)         Translate a string to all
  14753.                                           upper- or all lower-case
  14754.  
  14755.  
  14756.  
  14757.  
  14758.  
  14759.  
  14760.  
  14761.  
  14762.  
  14763.  
  14764.  
  14765.  
  14766.  
  14767.  
  14768.  
  14769.  
  14770.  
  14771.  
  14772.  
  14773.  
  14774.  
  14775.  
  14776.  
  14777.  
  14778.  
  14779.  
  14780.  
  14781.  
  14782.  
  14783.  
  14784.  
  14785.  
  14786.  
  14787.  
  14788.  
  14789.  
  14790.  
  14791.  
  14792.  
  14793.  
  14794.  
  14795.  
  14796.  
  14797.  
  14798.  
  14799.  
  14800.  
  14801.  
  14802.  
  14803.  
  14804.                                      Page 232
  14805.  
  14806.                                                           Built-in Procedures
  14807.  
  14808.  
  14809.  
  14810.                                         
  14811.  
  14812.  
  14813.  
  14814.  
  14815.                             Printf Format Directives
  14816.  
  14817.  
  14818.                    These argument formats are recognized by printf:
  14819.  
  14820.                       %c        Single character.
  14821.                       %d        Decimal number.
  14822.                       %e        [-]d.dddddde[+-]ddd
  14823.                       %f        [-]ddd.dddddd
  14824.                       %g        %e or %f formatting, whichever is
  14825.                                 shorter.
  14826.                       %o        Unsigned octal number.
  14827.                       %s        String.
  14828.                       %x        unsigned hexadecimal number.
  14829.                       %%        Literal % character.
  14830.                       
  14831.                    Additional parameters may lie between the % and
  14832.                    the control letter:
  14833.  
  14834.                       -         Left-justify expression in its field.
  14835.                       width     Pad field to this width as needed;
  14836.                                 leading 0 pads with zeros.
  14837.                       .prec     Maximum string width or digits to
  14838.                                 right of decimal point.
  14839.  
  14840.  
  14841.  
  14842.  
  14843.  
  14844.  
  14845.  
  14846.  
  14847.  
  14848.  
  14849.  
  14850.  
  14851.  
  14852.  
  14853.  
  14854.  
  14855.  
  14856.  
  14857.  
  14858.  
  14859.  
  14860.  
  14861.  
  14862.  
  14863.  
  14864.  
  14865.  
  14866.                                      Page 233
  14867.  
  14868.      Built-in Procedures
  14869.  
  14870.  
  14871.             
  14872.  
  14873.  
  14874.  
  14875.  
  14876.  
  14877.  
  14878.  
  14879.  
  14880.  
  14881.  
  14882.  
  14883.  
  14884.  
  14885.  
  14886.  
  14887.  
  14888.  
  14889.  
  14890.  
  14891.  
  14892.  
  14893.  
  14894.  
  14895.  
  14896.  
  14897.  
  14898.  
  14899.  
  14900.  
  14901.  
  14902.  
  14903.  
  14904.  
  14905.  
  14906.  
  14907.  
  14908.  
  14909.  
  14910.  
  14911.  
  14912.  
  14913.  
  14914.  
  14915.  
  14916.  
  14917.  
  14918.  
  14919.  
  14920.  
  14921.  
  14922.  
  14923.  
  14924.  
  14925.  
  14926.  
  14927.  
  14928.                                      Page 234
  14929.  
  14930.                                                                     Utilities
  14931.  
  14932.  
  14933.             
  14934.  
  14935.  
  14936.                                Built-in Utilities
  14937.  
  14938.  
  14939.                    Command                Function               
  14940.  
  14941.                    cd                     Change working directory.
  14942.                                           Optionally, change disk.
  14943.  
  14944.                    chcp                   Change code page.  (Not
  14945.                                           implemented on NT.)
  14946.  
  14947.                    chdir                  A synonym for cd.
  14948.  
  14949.                    cls                    Clear the screen.
  14950.  
  14951.                    dirs                   Print the directory stack.
  14952.  
  14953.                    echo                   Echo arguments to stdout.
  14954.  
  14955.                    eval                   Defer parsing of the word
  14956.                                           list until the evaluation
  14957.                                           phase.
  14958.  
  14959.                    hashstat               Print path hash statistics.
  14960.  
  14961.                    heapstat               Print heap usage
  14962.                                           statistics.
  14963.  
  14964.                    history                Display the history list.
  14965.  
  14966.                    kill                   Kill background activity.
  14967.  
  14968.                    popd                   Pop directory stack.
  14969.  
  14970.                    ps                     List process and thread
  14971.                                           status.
  14972.  
  14973.                    pushd                  Push a new current
  14974.                                           directory on the directory
  14975.                                           stack or exchange the top
  14976.                                           two items.
  14977.  
  14978.                    rehash                 Rehash the path
  14979.                                           directories.
  14980.  
  14981.                    rotd                   Rotate the directory stack.
  14982.  
  14983.                    sleep                  Sleep for a specified
  14984.                                           period.
  14985.  
  14986.                    source                 Read commands from a file.
  14987.  
  14988.  
  14989.  
  14990.                                      Page 235
  14991.  
  14992.      Utilities
  14993.  
  14994.  
  14995.                    unhash                 Turn off path list hashing.
  14996.  
  14997.                    verify                 Turn on write verification
  14998.                                           mode.
  14999.  
  15000.                    wait                   Wait for children to
  15001.                                           complete.
  15002.  
  15003.  
  15004.                    All built-in utilities self-document with the -h
  15005.                    option.
  15006.  
  15007.  
  15008.  
  15009.  
  15010.  
  15011.  
  15012.  
  15013.  
  15014.  
  15015.  
  15016.  
  15017.  
  15018.  
  15019.  
  15020.  
  15021.  
  15022.  
  15023.  
  15024.  
  15025.  
  15026.  
  15027.  
  15028.  
  15029.  
  15030.  
  15031.  
  15032.  
  15033.  
  15034.  
  15035.  
  15036.  
  15037.  
  15038.  
  15039.  
  15040.  
  15041.  
  15042.  
  15043.  
  15044.  
  15045.  
  15046.  
  15047.  
  15048.  
  15049.  
  15050.  
  15051.  
  15052.                                      Page 236
  15053.  
  15054.                                                                     Utilities
  15055.  
  15056.  
  15057.             
  15058.  
  15059.  
  15060.                                External Utilities
  15061.  
  15062.  
  15063.                    Command                Function               
  15064.  
  15065.                    binedit                Binary edit.
  15066.  
  15067.                    cat                    Concatenate files.
  15068.  
  15069.                    chmod                  Change mode bits of file.
  15070.  
  15071.                    cp                     Copy files or directories.
  15072.  
  15073.                    cron                   Run commands at specified
  15074.                                           times.
  15075.  
  15076.                    cut                    Cut out selected fields of
  15077.                                           each line of text.
  15078.  
  15079.                    des                    Encrypt or decrypt data
  15080.                                           using the Data Encryption
  15081.                                           Standard (DES).  Due to
  15082.                                           U.S. Federal Law, this
  15083.                                           utility cannot be exported
  15084.                                           outside the U.S. or Canada.
  15085.  
  15086.                    date                   Display the date and time.
  15087.  
  15088.                    diff                   Compare files or
  15089.                                           directories.
  15090.  
  15091.                    dim                    Discard any ansi escape
  15092.                                           sequences in the input
  15093.                                           stream.
  15094.  
  15095.                    dskread                Read raw sectors from a
  15096.                                           disk.
  15097.  
  15098.                    dskwrite               Write raw sectors to a
  15099.                                           disk.
  15100.  
  15101.                    du                     Display disk usage.
  15102.  
  15103.                    fgrep                  Fast string search (fast
  15104.                                           grep) of text files.
  15105.  
  15106.                    grep                   Regular expression pattern
  15107.                                           search of text files.
  15108.  
  15109.                    head                   Copy the first few lines or
  15110.                                           bytes of a file to stdout.
  15111.  
  15112.  
  15113.  
  15114.                                      Page 237
  15115.  
  15116.      Utilities
  15117.  
  15118.  
  15119.                    label                  Read/Write the volume
  15120.                                           label.
  15121.  
  15122.                    ls                     List directory contents.
  15123.  
  15124.                    markexe                Mark an .exe file to
  15125.                                           indicate what sort of
  15126.                                           application it is.  (OS/2
  15127.                                           only.)
  15128.  
  15129.                    mkdir                  Make a new directory.
  15130.  
  15131.                    more                   A better more utility.
  15132.                                           (Able to search forward or
  15133.                                           backward or to a specific
  15134.                                           line.)
  15135.  
  15136.  
  15137.  
  15138.  
  15139.  
  15140.  
  15141.  
  15142.  
  15143.  
  15144.  
  15145.  
  15146.  
  15147.  
  15148.  
  15149.  
  15150.  
  15151.  
  15152.  
  15153.  
  15154.  
  15155.  
  15156.  
  15157.  
  15158.  
  15159.  
  15160.  
  15161.  
  15162.  
  15163.  
  15164.  
  15165.  
  15166.  
  15167.  
  15168.  
  15169.  
  15170.  
  15171.  
  15172.  
  15173.  
  15174.  
  15175.  
  15176.                                      Page 238
  15177.  
  15178.                                                                     Utilities
  15179.  
  15180.  
  15181.             
  15182.  
  15183.  
  15184.                                External Utilities
  15185.  
  15186.  
  15187.                    Command                Function               
  15188.  
  15189.                    moreh                  A large model version of
  15190.                                           more.
  15191.  
  15192.                    mt                     Manipulate the tape device.
  15193.                                           (NT only.)
  15194.  
  15195.                    mv                     Move files or directories.
  15196.  
  15197.                    newer                  Test whether first file is
  15198.                                           newer than the others.
  15199.  
  15200.                    older                  Test whether first file is
  15201.                                           older than the others.
  15202.  
  15203.                    patchlnk               A (very) special-purpose
  15204.                                           utility to patch a bug in
  15205.                                           the Microsoft linker on
  15206.                                           OS/2.
  15207.  
  15208.                    pwd                    Print the working
  15209.                                           directories.
  15210.  
  15211.                    rm                     Remove files or
  15212.                                           directories.
  15213.  
  15214.                    rmdir                  Remove directories.
  15215.  
  15216.                    sed                    Stream editor.
  15217.  
  15218.                    setrows                Set or report the number of
  15219.                                           rows in the display window.
  15220.                                           (OS/2 only.)
  15221.  
  15222.                    split                  Split a large file into
  15223.                                           equal-sized chunks.
  15224.  
  15225.                    startwin               Start Win3.x applications
  15226.                                           under OS/2 2.x.
  15227.  
  15228.                    strings                Extract ASCII strings from
  15229.                                           a file.
  15230.  
  15231.                    sum                    Checksum the contents of a
  15232.                                           file.
  15233.  
  15234.                    tabs                   Expand/Unexpand tabs.
  15235.  
  15236.  
  15237.  
  15238.                                      Page 239
  15239.  
  15240.      Utilities
  15241.  
  15242.  
  15243.                    tail                   Copy the last few lines or
  15244.                                           bytes of a file to stdout.
  15245.  
  15246.                    tar                    Read/Write UNIX tape
  15247.                                           archive (tar) format files.
  15248.  
  15249.                    tee                    Pipe fitting.
  15250.  
  15251.                    touch                  Update the time-stamp on a
  15252.                                           file.
  15253.  
  15254.                    tr                     Translate characters.
  15255.  
  15256.                    uniq                   Report unique lines in text
  15257.                                           files.
  15258.  
  15259.  
  15260.  
  15261.  
  15262.  
  15263.  
  15264.  
  15265.  
  15266.  
  15267.  
  15268.  
  15269.  
  15270.  
  15271.  
  15272.  
  15273.  
  15274.  
  15275.  
  15276.  
  15277.  
  15278.  
  15279.  
  15280.  
  15281.  
  15282.  
  15283.  
  15284.  
  15285.  
  15286.  
  15287.  
  15288.  
  15289.  
  15290.  
  15291.  
  15292.  
  15293.  
  15294.  
  15295.  
  15296.  
  15297.  
  15298.  
  15299.  
  15300.                                      Page 240
  15301.  
  15302.                                                                     Utilities
  15303.  
  15304.  
  15305.             
  15306.  
  15307.  
  15308.                                External Utilities
  15309.  
  15310.  
  15311.                    Command                Function               
  15312.  
  15313.                    ver                    Display the current system
  15314.                                           and Hamilton C shell
  15315.                                           version numbers.
  15316.  
  15317.                    vol                    Display the disk volume
  15318.                                           label.
  15319.  
  15320.                    wc                     Count lines, words and
  15321.                                           characters.
  15322.  
  15323.                    whereis                Tell which PATH directory a
  15324.                                           given executable is in.
  15325.  
  15326.                    xd                     Hex dump a file to stdout.
  15327.  
  15328.  
  15329.                    All external utilities except whereis self-
  15330.                    document with the -h option.  Any external utility
  15331.                    may be renamed simply by renaming the executable
  15332.                    file.
  15333.  
  15334.  
  15335.  
  15336.                                         
  15337.  
  15338.  
  15339.  
  15340.  
  15341.  
  15342.  
  15343.  
  15344.  
  15345.  
  15346.  
  15347.  
  15348.  
  15349.  
  15350.  
  15351.  
  15352.  
  15353.  
  15354.  
  15355.  
  15356.  
  15357.  
  15358.  
  15359.  
  15360.  
  15361.  
  15362.                                      Page 241
  15363.  
  15364.      Popular Aliases
  15365.  
  15366.  
  15367.             
  15368.  
  15369.  
  15370.                                  Popular Aliases
  15371.  
  15372.  
  15373.                    Command   Definition   Function               
  15374.  
  15375.                    app       cat >>       Append to a file.
  15376.  
  15377.                    beep      eval echo -n ^a   Beep sound.
  15378.  
  15379.                    breaksw   break        Older BSD4.3 name for a
  15380.                                           break statement inside a
  15381.                                           switch.
  15382.  
  15383.                    cdd       cd +c        Change the directory and
  15384.                                           disk in one command.
  15385.  
  15386.                    copy      local s ; @ s = $nowild ; @ nowild = 1 ;
  15387.                                           safecopy
  15388.                                           Invoke the standard IBM/MS
  15389.                                           copy command with shell
  15390.                                           wildcarding turned off so
  15391.                                           copy will work sensibly.
  15392.  
  15393.                    date      dt           Display the current time
  15394.                                           and date.
  15395.  
  15396.                    del       local s ; @ s = $nowild ; @ nowild = 1 ;
  15397.                                           safedel
  15398.                                           Invoke the del command with
  15399.                                           shell wildcarding turned
  15400.                                           off so ``del *.*'' will
  15401.                                           still produce the ``Are you
  15402.                                           sure?'' message.
  15403.  
  15404.                    di        diff -b!     Run the diff command,
  15405.                                           ignoring white space
  15406.                                           differences and using color
  15407.                                           to highlight the changes.
  15408.  
  15409.                    dir       cmd /c dir   Invoke the cmd.exe dir
  15410.                                           command.  (Alternately, you
  15411.                                           may wish to intercept dir
  15412.                                           the same way copy or del is
  15413.                                           done, turning off shell
  15414.                                           wildcarding before running
  15415.                                           the command.)
  15416.  
  15417.                    duc       du -c        Disk usage for the current
  15418.                                           disk only.
  15419.  
  15420.  
  15421.  
  15422.  
  15423.  
  15424.                                      Page 242
  15425.  
  15426.                                                               Popular Aliases
  15427.  
  15428.  
  15429.                    dumphist  history -s > ~\history.csh
  15430.                                           Dump out the history list.
  15431.  
  15432.                    endif     end          Older BSD4.3 name for the
  15433.                                           end of an if statement.
  15434.  
  15435.                    endsw     end          Older BSD4.3 name for the
  15436.                                           end of switch statement.
  15437.  
  15438.                    erase     del          Alternate name for del.
  15439.  
  15440.                    f         fgrep        Quicker name for fgrep.
  15441.  
  15442.                    fn        fgrep -n     Fgrep and print line
  15443.                                           numbers.
  15444.  
  15445.  
  15446.  
  15447.  
  15448.  
  15449.  
  15450.  
  15451.  
  15452.  
  15453.  
  15454.  
  15455.  
  15456.  
  15457.  
  15458.  
  15459.  
  15460.  
  15461.  
  15462.  
  15463.  
  15464.  
  15465.  
  15466.  
  15467.  
  15468.  
  15469.  
  15470.  
  15471.  
  15472.  
  15473.  
  15474.  
  15475.  
  15476.  
  15477.  
  15478.  
  15479.  
  15480.  
  15481.  
  15482.  
  15483.  
  15484.  
  15485.  
  15486.                                      Page 243
  15487.  
  15488.      Popular Aliases
  15489.  
  15490.  
  15491.             
  15492.  
  15493.  
  15494.                                  Popular Aliases
  15495.  
  15496.  
  15497.                    Command   Definition   Function               
  15498.  
  15499.                    g         grep         Quicker name for grep.
  15500.  
  15501.                    h         history      Quicker name for history.
  15502.  
  15503.                    help                   Under OS/2, invoke the
  15504.                                           IBM/Microsoft help command.
  15505.                                           Under NT, this is a
  15506.                                           procedure using winerror
  15507.                                           (in the samples directory)
  15508.                                           to print the message
  15509.                                           corresponding to the return
  15510.                                           code from the last command.
  15511.  
  15512.                    home      cdd ~        Change to the home disk and
  15513.                                           directory.
  15514.  
  15515.                    ld        ls -a +D -.  List only the
  15516.                                           subdirectories.
  15517.  
  15518.                    ll        ls -L        List directories, long
  15519.                                           format.
  15520.  
  15521.                    loadhist  source -n ~\history.csh
  15522.                                           Load the history list
  15523.                                           without executing any of
  15524.                                           it.
  15525.  
  15526.                    md        mkdir        Make directories.
  15527.  
  15528.                    mi        moreh -i     Quick interactive startup
  15529.                                           of your favorite version
  15530.                                           more.  Clears the screen
  15531.                                           when it starts up and
  15532.                                           doesn't just exit if
  15533.                                           there's less than a
  15534.                                           screenful.
  15535.  
  15536.                    mih       moreh -i     Huge interactive more.
  15537.  
  15538.                    mis       more -i      Small interactive more.
  15539.  
  15540.                    pause     echo -n Press any key when ready ... ; @
  15541.                                           getchar ; echo
  15542.                                           Pause, waiting for any
  15543.                                           keystroke or character from
  15544.                                           stdin.
  15545.  
  15546.  
  15547.  
  15548.                                      Page 244
  15549.  
  15550.                                                               Popular Aliases
  15551.  
  15552.  
  15553.                    q         exit         Exit the C shell
  15554.  
  15555.                    rd        rmdir        Remove empty directories.
  15556.  
  15557.                    ren       rename       Another name for the rename
  15558.                                           alias.
  15559.  
  15560.                    rename    local s ; @ s = nowild ; @ nowild = 1 ;
  15561.                                           saferename
  15562.                                           Invoke the standard IBM/MS
  15563.                                           rename command with shell
  15564.                                           wildcarding turned off so
  15565.                                           the rename will work
  15566.                                           sensibly.
  15567.  
  15568.  
  15569.  
  15570.  
  15571.  
  15572.  
  15573.  
  15574.  
  15575.  
  15576.  
  15577.  
  15578.  
  15579.  
  15580.  
  15581.  
  15582.  
  15583.  
  15584.  
  15585.  
  15586.  
  15587.  
  15588.  
  15589.  
  15590.  
  15591.  
  15592.  
  15593.  
  15594.  
  15595.  
  15596.  
  15597.  
  15598.  
  15599.  
  15600.  
  15601.  
  15602.  
  15603.  
  15604.  
  15605.  
  15606.  
  15607.  
  15608.  
  15609.  
  15610.                                      Page 245
  15611.  
  15612.      Popular Aliases
  15613.  
  15614.  
  15615.             
  15616.  
  15617.  
  15618.                                  Popular Aliases
  15619.  
  15620.  
  15621.                    Command   Definition   Function               
  15622.  
  15623.                    start     cmd /c start Start a new session via the
  15624.                                           cmd.exe start command.
  15625.  
  15626.                    type      cat          Copy files to stdout.
  15627.  
  15628.                    vol       vl           List volume labels.
  15629.  
  15630.                    w         (wait; beep) Wait for background
  15631.                                           processes and beep.
  15632.  
  15633.                    xcopy     local s ; @ s = nowild ; @ nowild = 1 ;
  15634.                                           safexcopy
  15635.                                           Invoke the standard IBM/MS
  15636.                                           xcopy command with shell
  15637.                                           wildcarding turned off so
  15638.                                           xcopy will work sensibly.
  15639.  
  15640.  
  15641.  
  15642.  
  15643.  
  15644.  
  15645.  
  15646.  
  15647.  
  15648.  
  15649.  
  15650.  
  15651.  
  15652.  
  15653.  
  15654.  
  15655.  
  15656.  
  15657.  
  15658.  
  15659.  
  15660.  
  15661.  
  15662.  
  15663.  
  15664.  
  15665.  
  15666.  
  15667.  
  15668.  
  15669.  
  15670.  
  15671.  
  15672.                                      Page 246
  15673.  
  15674.                                                               Popular Aliases
  15675.  
  15676.  
  15677.             
  15678.  
  15679.  
  15680.  
  15681.  
  15682.  
  15683.  
  15684.  
  15685.  
  15686.  
  15687.  
  15688.  
  15689.  
  15690.  
  15691.  
  15692.  
  15693.  
  15694.  
  15695.  
  15696.  
  15697.  
  15698.  
  15699.  
  15700.  
  15701.  
  15702.  
  15703.  
  15704.  
  15705.  
  15706.  
  15707.  
  15708.  
  15709.  
  15710.  
  15711.  
  15712.  
  15713.  
  15714.  
  15715.  
  15716.  
  15717.  
  15718.  
  15719.  
  15720.  
  15721.  
  15722.  
  15723.  
  15724.  
  15725.  
  15726.  
  15727.  
  15728.  
  15729.  
  15730.  
  15731.  
  15732.  
  15733.  
  15734.                                      Page 247
  15735.  
  15736.      Help
  15737.  
  15738.  
  15739.  
  15740.                             Help for Hamilton C shell
  15741.  
  15742.  
  15743.             csh:      Startup the Hamilton C shell
  15744.  
  15745.                  Usage:  csh [-!BbefFhHiKLlNnstuXYZ-] [-IO] [+IO] [-
  15746.                  cC command]
  15747.                            [arguments ... ]
  15748.  
  15749.                  Options:
  15750.  
  15751.                      -!  Ignore errors:  Continue execution even if a
  15752.                          command terminates abnormally.  (Implied by
  15753.                          interactive.)
  15754.                      -B  Berkeley mode for better compatibility with
  15755.                          the BSD4.3 C shell for commands typed, not
  15756.                          just those read from a script starting with
  15757.                          #!/bin/csh.
  15758.                      -b  No Berkeley compatibility mode at all, not
  15759.                          even on scripts starting with #!/bin/csh.
  15760.                      -c  Execute the command following on the command
  15761.                          line, then exit.  (Implies not interactive.)
  15762.                      -C  Normally, this means immediately run the
  15763.                          command on the command line, then continue
  15764.                          with normal startup and processing of stdin.
  15765.                          But for compatibility with cmd.exe, the -X
  15766.                          option may be used to toggle this to have
  15767.                          the same meaning as -c but with the initial
  15768.                          greeting and copyright notice suppressed.
  15769.                      -e  Echo the raw input to stdout.
  15770.                      -f  Fast startup:  Don't look for a startup.csh
  15771.                          file.
  15772.                      -F  Faster startup:  Don't look for a
  15773.                          startup.csh file and don't hash the path
  15774.                          directories.
  15775.                      -H  Heapstats.  At some penalty in performance,
  15776.                          this causes the shell to keep a count of the
  15777.                          number and total size of all objects
  15778.                          allocated or freed from the heap.
  15779.                          Statistics can be displayed using the
  15780.                          heapstat command.
  15781.                      -i  Interactive (even if stdin appears to be a
  15782.                          file or a pipe):  Prompt for input and show
  15783.                          the result of history substitutions.
  15784.                      -I  Start with command-line editing in insert
  15785.                          mode.
  15786.                      +I  Start every command in insert mode.
  15787.                      -K  Do a fast startup, skipping both the
  15788.                          login.csh and startup.csh files, run the
  15789.                          command on the command line, and exit.
  15790.                      -L  Login shell:  Look for login.csh and
  15791.                          logout.csh and do history save at exit if
  15792.                          savehist == 1.
  15793.  
  15794.  
  15795.  
  15796.                                      Page 248
  15797.  
  15798.                                                                          Help
  15799.  
  15800.  
  15801.                      -l  same as -L.
  15802.                      -N  No space after the last filename generated
  15803.                          by filename completion.  (It's convenient to
  15804.                          set this with CSHOPTIONS.)
  15805.                      -n  No execution:  Parse commands looking for
  15806.                          syntax errors but don't execute them.
  15807.                      -O  Start with command-line editing in
  15808.                          overstrike (default) mode.
  15809.                      +O  Start every command in overstrike mode.
  15810.                      -s  Read and execute a single line from stdin.
  15811.                          (Implies not interactive.)
  15812.                      -t  Suppress callstack tracing.  Error messages
  15813.                          will not include a dump of the callstack but
  15814.                          performance will be improved slightly.
  15815.                      -u  Reads from devices or pipes should be
  15816.                          unbuffered.  (Intended to all the shell to
  15817.                          be used over a comm line.)
  15818.                      -X  Toggle between the normal meaning of -C and
  15819.                          a cmd.exe-compatible interpretation.  You
  15820.                          can set this with the CSHOPTIONS
  15821.                          environmental variable in combination with
  15822.                          setting COMSPEC to point to the C shell to
  15823.                          allow programs that use /C to pass commands
  15824.                          to cmd.exe to be used with the C shell
  15825.                          instead.
  15826.                      -Y  No interrupts.  Don't install an interrupt
  15827.                          handler during startup.  (Ignored under
  15828.                          Windows NT.)
  15829.                      -Z  Very special purpose:  Don't bump the
  15830.                          maximum file handle count during shell
  15831.                          initialization.  Use this option under OS/2
  15832.                          as a workaround if you encounter an
  15833.                          application that fails if it inherits a
  15834.                          larger limit.  This option only works from
  15835.                          the Start Programs or Group menus, not the
  15836.                          command line.  Under NT, this option affects
  15837.                          only the limit on the number of open file
  15838.                          handles on a FAT filesystem; it has no
  15839.                          effect on HPFS or NTFS files.
  15840.                      -h  Help.
  15841.                      --  End of options.
  15842.  
  15843.  
  15844.             (If preferred,  the slash, ``/,'' may be used in place of
  15845.             a minus to introduce options.)
  15846.  
  15847.  
  15848.  
  15849.  
  15850.  
  15851.  
  15852.  
  15853.  
  15854.  
  15855.  
  15856.  
  15857.  
  15858.                                      Page 249
  15859.  
  15860.      Help
  15861.  
  15862.  
  15863.  
  15864.                              Help for the Utilities
  15865.  
  15866.  
  15867.             binedit:  Binary Edit
  15868.  
  15869.                  Usage:  binedit [-ih!-] [-r replace] search file1 [
  15870.                  file2 ... ]
  15871.  
  15872.                     binedit is  a very  simple utility  for  scanning
  15873.                     arbitrary  files,   looking  for  and  optionally
  15874.                     changing any references to the search argument to
  15875.                     the replacement  value.   binedit is quite useful
  15876.                     patching  binary  files,  e.g.,  to  replace  all
  15877.                     occurrences of C:\OS2 with C:\1.X.
  15878.  
  15879.                     Occurrences will  be reported as hex offsets from
  15880.                     the start  of the  files you  name.   You can use
  15881.                     these numbers  to go examine the file with IBM/MS
  15882.                     patch.exe  if   you  like  and  make  the  change
  15883.                     manually.
  15884.  
  15885.                     You can  also ask  binedit to  make  the  change,
  15886.                     using the  -r (replace)  option.   Nothing fancy.
  15887.                     It just changes all occurrences to the string you
  15888.                     specify and quits.
  15889.  
  15890.                     Neither the  search nor  the replace  string  may
  15891.                     contain null  characters, but otherwise there are
  15892.                     no restrictions.
  15893.  
  15894.                  Options:
  15895.  
  15896.                      -h  Help.  (This screen.)
  15897.                      -i  Ignore character case in the search
  15898.                          argument.
  15899.                      -r replace Replace any occurrences of the search
  15900.                                 string with this replacement value.
  15901.                      -!  Pad with nulls or truncate the replace
  15902.                          string to be the same length as the search
  15903.                          string.  (Otherwise, it's an error if
  15904.                          they're different lengths.)
  15905.                      --  End of options.
  15906.  
  15907.  
  15908.             cat:      Concatenate Files to Stdout
  15909.  
  15910.                  Usage:  cat [-h-] [ file1 file2 ... ]
  15911.  
  15912.                     cat copies the files you specify, one immediately
  15913.                     after another,  onto stdout.   No  end-of-file or
  15914.                     other delimiter  characters are  inserted between
  15915.                     files.
  15916.  
  15917.  
  15918.  
  15919.  
  15920.                                      Page 250
  15921.  
  15922.                                                                          Help
  15923.  
  15924.  
  15925.                  Options:
  15926.  
  15927.                      -h  Help.
  15928.                      --  End of options.
  15929.  
  15930.  
  15931.             cd:       Change to a New Current Directory
  15932.  
  15933.                  Usage:  cd [-chr-] [+chr] [ directory ]
  15934.  
  15935.                     cd works  exactly like  the  one  in  cmd.exe  by
  15936.                     default:  if you specify a directory, it tries to
  15937.                     make that  the current  on appropriate  disk  but
  15938.                     won't change  your current  disk.   If you  don't
  15939.                     specify  a  directory,  it  reports  the  current
  15940.                     setting.
  15941.  
  15942.                     If the  path you  specify is just 3 or more dots,
  15943.                     cd will interpret that specially.  Just as ``..''
  15944.                     means go up one level, ``...'' means up 2 levels,
  15945.                     ``....'' means  up 3  levels,  etc.    Note  that
  15946.                     ``...'' is  also a  wildcard notation for zero or
  15947.                     more directory  levels, but only if it's preceded
  15948.                     by ``\'',  ``/'', ``~''  or ``:''  or followed by
  15949.                     ``\'' or  ``/'', so  usually there's  no conflict
  15950.                     with  this   notation  for   going  up   multiple
  15951.                     directories with cd.  The exception is when you'd
  15952.                     like  to   go  up   multiple  directories  on  an
  15953.                     explicitly specified  drive; in that case, you'll
  15954.                     have  to   quote  the   word  to   turn  off  the
  15955.                     wildcarding.
  15956.  
  15957.                     This version  of cd also supports CDPATH.  If you
  15958.                     specify a  path that  isn't found,  cd will  look
  15959.                     through the  list of  any directories you specify
  15960.                     in the  CDPATH  environmental  variable  (or  the
  15961.                     equivalent cdpath  shell variable)  to see if the
  15962.                     directory  you   want  is   in   one   of   those
  15963.                     directories.  The syntax for CDPATH and cdpath is
  15964.                     the same  as for  PATH or  path except  that  the
  15965.                     current directory need not be listed.
  15966.  
  15967.                     (See  also   the  dirs,   pushd,  popd  and  rotd
  15968.                     commands.)
  15969.  
  15970.                  Options:
  15971.  
  15972.                     If you  set the  chgdisk variable equal to 1 (its
  15973.                     default  is  0),  cd  will  automatically  change
  15974.                     current disks  if the  directory  is  on  another
  15975.                     drive.  The  +c  and  -c  options  allow  you  to
  15976.                     manually control this drive switching:
  15977.  
  15978.                      +c  Automatically change the current disk.
  15979.  
  15980.  
  15981.  
  15982.                                      Page 251
  15983.  
  15984.      Help
  15985.  
  15986.  
  15987.                      -c  Don't automatically change current disk.
  15988.  
  15989.                     If you  set the cdhome variable to 1 (its default
  15990.                     is 0),  cd will  change to your home directory if
  15991.                     you specify one instead of reporting your current
  15992.                     position.  You can manually control this with the
  15993.                     +r and -r options:
  15994.  
  15995.                      +r  Report but don't change the current
  15996.                          directory if no destination directory is
  15997.                          specified.
  15998.                      -r  Change to the home directory in this
  15999.                          situation.
  16000.  
  16001.  
  16002.  
  16003.  
  16004.  
  16005.  
  16006.  
  16007.  
  16008.  
  16009.  
  16010.  
  16011.  
  16012.  
  16013.  
  16014.  
  16015.  
  16016.  
  16017.  
  16018.  
  16019.  
  16020.  
  16021.  
  16022.  
  16023.  
  16024.  
  16025.  
  16026.  
  16027.  
  16028.  
  16029.  
  16030.  
  16031.  
  16032.  
  16033.  
  16034.  
  16035.  
  16036.  
  16037.  
  16038.  
  16039.  
  16040.  
  16041.  
  16042.  
  16043.  
  16044.                                      Page 252
  16045.  
  16046.                                                                          Help
  16047.  
  16048.  
  16049.                      -h  Help.
  16050.                      --  End of options.
  16051.  
  16052.  
  16053.             chcp:     Report or Change the Code Page
  16054.  
  16055.                  Usage:  chcp [-h-] [ page ]
  16056.  
  16057.                     Change to  the specified  OS/2 character set code
  16058.                     page.   If  no  page  is  specified,  report  the
  16059.                     current active and prepared pages.  (This command
  16060.                     is not yet supported under NT.)
  16061.  
  16062.                  Options:
  16063.  
  16064.                      -h  Help.
  16065.                      --  End of options.
  16066.  
  16067.  
  16068.             chmod:    Change Mode Bits on Files or Directories
  16069.  
  16070.                  Usage:  chmod [-+] [rRAHSh] pathname1 [ pathname2
  16071.                  ... ]
  16072.  
  16073.                  Options:
  16074.  
  16075.                      -r  Recursively change contents of directories.
  16076.                      +R  Read-only mode is set.  (The file is write-
  16077.                          protected.)
  16078.                      -R  Read-only mode is turned off.
  16079.                      +A  Archive bit is set.
  16080.                      -A  Archive bit is turned off.
  16081.                      +H  Hidden mode is set.
  16082.                      -H  Hidden mode is turned off.
  16083.                      +S  Mark as a System file.
  16084.                      -S  Mark as a normal user file.
  16085.                      -h  Help.
  16086.                      --  End of options.
  16087.  
  16088.  
  16089.             cls:      Clear the Screen
  16090.  
  16091.                  Usage:  cls [-h-]
  16092.  
  16093.                  Options:
  16094.  
  16095.                      -h  Help.
  16096.                      --  End of options.
  16097.  
  16098.  
  16099.  
  16100.  
  16101.  
  16102.  
  16103.  
  16104.  
  16105.  
  16106.                                      Page 253
  16107.  
  16108.      Help
  16109.  
  16110.  
  16111.             cp:       Copy Files or Directories
  16112.  
  16113.                  Usage:  cp [-filmh-] source1 [ source2 ... ]
  16114.                  destination
  16115.  
  16116.                     cp can  copy both  files and directories.  If the
  16117.                     destination is  an existing directory, the source
  16118.                     object(s) will be copied into that directory.  If
  16119.                     more than  one source  object is  specified,  the
  16120.                     destination must  be a directory, but it need not
  16121.                     already exist.
  16122.  
  16123.                     If a  destination file already exists, it will be
  16124.                     overwritten; this  is not considered an error and
  16125.                     no diagnostic message is given.
  16126.  
  16127.                  Options:
  16128.  
  16129.                      -f  Force read-only files to be overwritten.
  16130.                      -i  Interactive:  ask before copying each object
  16131.                          on the command line.
  16132.                      -l  Logging is on:  display the name of each
  16133.                          file or directory as it's copied.
  16134.                      -m  Merge sub-directories of same name in source
  16135.                          and destination.
  16136.                      -h  Help.
  16137.                      --  End of options.  (Useful if filenames start
  16138.                          with ``-''.)
  16139.  
  16140.  
  16141.  
  16142.  
  16143.  
  16144.  
  16145.  
  16146.  
  16147.  
  16148.  
  16149.  
  16150.  
  16151.  
  16152.  
  16153.  
  16154.  
  16155.  
  16156.  
  16157.  
  16158.  
  16159.  
  16160.  
  16161.  
  16162.  
  16163.  
  16164.  
  16165.  
  16166.  
  16167.  
  16168.                                      Page 254
  16169.  
  16170.                                                                          Help
  16171.  
  16172.  
  16173.             cron:     Run Commands at Specified Times
  16174.  
  16175.                  Usage:  cron [-asLwh-] [-o<opt>] [-d <dir>] [
  16176.                  crontab1 crontab2 ... ]
  16177.  
  16178.                     cron executes  commands at times according to the
  16179.                     crontab (.crt)  files  specifed.    If  any  path
  16180.                     specified is  a  directory,  cron  will  run  any
  16181.                     crontab  files   in   that   directory   or   any
  16182.                     subdirectory.   If no  files are  specified, cron
  16183.                     will read the crontab from stdin.
  16184.  
  16185.                     Each file  is  expected  to  contain  a  list  of
  16186.                     activities to  be run at certain times, specified
  16187.                     one per  line.   There are  six fields  per line,
  16188.                     separated  by   white  space.    The  first  five
  16189.                     specify:
  16190.  
  16191.                        minute         (0-59)
  16192.                        hour           (0-23)
  16193.                        day of the month   (1-31)
  16194.                        month of the year  (1-12)
  16195.                        day of the week    (0-6, 0 is Sunday)
  16196.  
  16197.                     Each of  these fields may be an asterisk (meaning
  16198.                     all legal  values) or  a comma-separated  list of
  16199.                     elements, where  each element  is either a single
  16200.                     number or a range, given as two numbers separated
  16201.                     by a minus.  If either end of a range is omitted,
  16202.                     it defaults to the highest/lowest legal value, as
  16203.                     appropriate.   If the  days are specified in both
  16204.                     day of  the month and day of the week fields, the
  16205.                     union of  those fields  is used;  to specify  the
  16206.                     days by  only one  field, the  other should be an
  16207.                     asterisk.   For example,  0 0 1 * 1 means run the
  16208.                     command at  midnight on  the first of every month
  16209.                     and also on every Monday.
  16210.  
  16211.                     The sixth field of each line is a command that is
  16212.                     to be  executed by  the shell  at  the  specified
  16213.                     times.   Any percent  characters  in  this  field
  16214.                     (unless escaped  by  the  escape  character)  are
  16215.                     translated     to     carriage     return/newline
  16216.                     combinations.   Only the  first line  (up to  the
  16217.                     first %  or end  of line) is passed as a command;
  16218.                     the other  lines are  written  to  the  shell  as
  16219.                     stdin.   If no  input lines  are given, the shell
  16220.                     will inherit stdin opened to the nul device.
  16221.  
  16222.                     If the  crontab was  read from  a file, the shell
  16223.                     will  inherit   stdout  and  stderr  handles  for
  16224.                     writing (appending,  if the  file already exists)
  16225.                     to a file created by replacing the .crt extension
  16226.                     on the  crontab file  with .nnn, where nnn is the
  16227.  
  16228.  
  16229.  
  16230.                                      Page 255
  16231.  
  16232.      Help
  16233.  
  16234.  
  16235.                     linenumber in the .crt file.  (If the crontab was
  16236.                     read from  stdin, then the shell will inherit the
  16237.                     stdout and  stderr that  cron inherited  when  it
  16238.                     started.)
  16239.  
  16240.                     If a  syntax or  other error  is encountered in a
  16241.                     crontab, that  line, but not the rest of the file
  16242.                     will be  ignored.   The rationale  is  that  cron
  16243.                     should continue  running even  if  it  encounters
  16244.                     problems; it  should not  be necessary to restart
  16245.                     it  just   because  one   entry  in  one  crontab
  16246.                     contained an error.
  16247.  
  16248.                     By default,  if the  crontab is read from a file,
  16249.                     commands will be run asynchronously, meaning that
  16250.                     all entries  that are  ready to  run at any given
  16251.                     time will  be quickly  spawned, one  right  after
  16252.                     another, without  waiting for  each  to  complete
  16253.                     before the  next is  spawned.   If the crontab is
  16254.                     read from  stdin, the default will be synchronous
  16255.                     execution, meaning  each must complete before the
  16256.                     next starts;  that's so any output from one won't
  16257.                     be jumbled  with that of another.  These defaults
  16258.                     can be overridden with command-line options.
  16259.  
  16260.                     Once it's started, cron will make an initial scan
  16261.                     of the  crontab files or directories.  Once every
  16262.                     minute after that it will look for any changes by
  16263.                     comparing timestamps on the files.
  16264.  
  16265.                  Options:
  16266.  
  16267.                      -a  Asynchronout execution.  Don't wait for one
  16268.                          command to complete before spawning the
  16269.                          next, even if the crontab was read from
  16270.                          stdin.
  16271.                      -s  Synchronous execution.   Always wait for one
  16272.                          command to complete before spawing the next,
  16273.                          even if the crontab was read from a file.
  16274.                      -L  Logging.  As each command is spawned,
  16275.                          timestamp and log it to stdout and to the
  16276.                          output file if that's not the same as
  16277.                          stdout.
  16278.                      -w  Wait 'till whole minute.  If cron wasn't
  16279.                          started near a whole minute (i.e., zero to
  16280.                          three seconds past a whole minute mark),
  16281.                          wait 'till the next whole minute before
  16282.                          beginning to schedule cron events.
  16283.                      -o<opt>    Remainder of word contains options to
  16284.                          be passed to the C shell with any commands.
  16285.                          E.g., -oF means C shell should do fast
  16286.                          startup when running commands.
  16287.  
  16288.  
  16289.  
  16290.  
  16291.  
  16292.                                      Page 256
  16293.  
  16294.                                                                          Help
  16295.  
  16296.  
  16297.                      -d <dir>   Output files should be created in the
  16298.                          specified directory, not the directory where
  16299.                          the .crt files were found.
  16300.                      -h  Help.  (This screen.)
  16301.                      --  End of options.
  16302.  
  16303.  
  16304.  
  16305.  
  16306.  
  16307.  
  16308.  
  16309.  
  16310.  
  16311.  
  16312.  
  16313.  
  16314.  
  16315.  
  16316.  
  16317.  
  16318.  
  16319.  
  16320.  
  16321.  
  16322.  
  16323.  
  16324.  
  16325.  
  16326.  
  16327.  
  16328.  
  16329.  
  16330.  
  16331.  
  16332.  
  16333.  
  16334.  
  16335.  
  16336.  
  16337.  
  16338.  
  16339.  
  16340.  
  16341.  
  16342.  
  16343.  
  16344.  
  16345.  
  16346.  
  16347.  
  16348.  
  16349.  
  16350.  
  16351.  
  16352.  
  16353.  
  16354.                                      Page 257
  16355.  
  16356.      Help
  16357.  
  16358.  
  16359.             cut:      Cut out selected fields of each line of text,
  16360.  
  16361.                  Usage:  cut [-hsr-] [-c<list>] [-f<list>] [-
  16362.                  d<delims>] [ file1 file2 ...]
  16363.  
  16364.                     cut can  be used  to select  certain  columns  or
  16365.                     fields from each line of input.  If the -c option
  16366.                     is used, fields are defined as specific character
  16367.                     positions.   If the -f option is used, the fields
  16368.                     can be  of variable  length, each field separated
  16369.                     from the  next by the delimiter character.  If no
  16370.                     files are  specified, cut  reads input  data from
  16371.                     stdin.
  16372.  
  16373.                     A  list  of  fields  or  character  positions  is
  16374.                     specified as  a comma-separated list of integers.
  16375.                     The minus  sign can  be used to indicate a range.
  16376.                     Here are  some examples:    1,4,7;  1-3,8;  -5,10
  16377.                     (short  for  1-5,10);  or  3-  (short  for  third
  16378.                     through last field.)
  16379.  
  16380.                  Options:
  16381.  
  16382.                      -h  Help.  (This screen.)
  16383.                      -s  Suppress lines with no delimiters in case of
  16384.                          -f option.  Otherwise, lines with no
  16385.                          delimiters are passed through unchanged.
  16386.                      -c<list>   The list specifies character
  16387.                                 positions.
  16388.                      -f<list>   The list specifies field numbers.
  16389.                      -d<delims> The specified characters are used as
  16390.                                 the field delimiters with the -f
  16391.                                 option.  Any number of delimiters can
  16392.                                 be specified.  The default is the tab
  16393.                                 character.
  16394.                      -r  Repeated delimiters are treated as if only a
  16395.                          single delimiter had appeared.
  16396.  
  16397.  
  16398.             date:     Print the Date and Time
  16399.  
  16400.                  Usage:  date [-nh-]
  16401.  
  16402.                     date prints  the day  of the  week, the  date and
  16403.                     time of day in 24-hour notation.  This command is
  16404.                     normally stored  in the  file dt.exe  and invoked
  16405.                     with an  alias so  it can  be used  from  cmd.exe
  16406.                     without colliding  with the internal cmd.exe date
  16407.                     function.
  16408.  
  16409.                  Options:
  16410.  
  16411.  
  16412.  
  16413.  
  16414.  
  16415.  
  16416.                                      Page 258
  16417.  
  16418.                                                                          Help
  16419.  
  16420.  
  16421.                      -n  Don't automatically append a Carriage
  16422.                          Return/Line Feed sequence to the end of the
  16423.                          output.
  16424.                      -h  Help.
  16425.                      --  End of options.
  16426.  
  16427.  
  16428.  
  16429.  
  16430.  
  16431.  
  16432.  
  16433.  
  16434.  
  16435.  
  16436.  
  16437.  
  16438.  
  16439.  
  16440.  
  16441.  
  16442.  
  16443.  
  16444.  
  16445.  
  16446.  
  16447.  
  16448.  
  16449.  
  16450.  
  16451.  
  16452.  
  16453.  
  16454.  
  16455.  
  16456.  
  16457.  
  16458.  
  16459.  
  16460.  
  16461.  
  16462.  
  16463.  
  16464.  
  16465.  
  16466.  
  16467.  
  16468.  
  16469.  
  16470.  
  16471.  
  16472.  
  16473.  
  16474.  
  16475.  
  16476.  
  16477.  
  16478.                                      Page 259
  16479.  
  16480.      Help
  16481.  
  16482.  
  16483.             des:      DES Data Encryption
  16484.  
  16485.                  Usage:  des [-edbhnrz-] [-k key] [ file1 file2 ... ]
  16486.  
  16487.                     des is  a filter  that encrypts  or decrypts data
  16488.                     read  from  the  files  you  specify,  one  after
  16489.                     another,  to  stdout  with  the  Data  Encryption
  16490.                     Standard (DES).  If no files are given, des reads
  16491.                     from stdin.  If there are multiple files, they're
  16492.                     simply concatenated as they're read.
  16493.  
  16494.                     Either -e  (encrypt)  or  -d  (decrypt)  must  be
  16495.                     specified. If the key is not given on the command
  16496.                     line with  the -k option, des will prompt for it,
  16497.                     suppressing echo.
  16498.  
  16499.                     Distribution of  this software  is controlled  by
  16500.                     U.S. Federal  Law under Title 22, Code of Federal
  16501.                     Regulations, Subchapter  M, Category XIII(b).  It
  16502.                     may not  be exported  outside the  U.S. or Canada
  16503.                     without an export license.
  16504.  
  16505.                  Options:
  16506.  
  16507.                      -e  Encrypt.
  16508.                      -d  Decrypt.
  16509.                      -b  Electronic Code Book (ECB) mode is used.
  16510.                          The default is to use DES Cipher Block
  16511.                          Chaining (CBC) mode with an initial vector
  16512.                          (IV) of all zeros.  Under ECB mode, each
  16513.                          block of 8 bytes is enciphered
  16514.                          independently, depending only on the key.
  16515.                          Under CBC mode, the enciphering of each
  16516.                          block also depends on the data in the
  16517.                          previous blocks.  The default CBC mode is
  16518.                          considered somewhat more secure.
  16519.                      -k key     Encryption key, typed as a simple
  16520.                                 ascii string.  With an ascii key, DES
  16521.                                 ignores the low order bit of each key
  16522.                                 byte but the high order bit is set
  16523.                                 for odd parity, thus retaining the
  16524.                                 information contained in the low
  16525.                                 order bit.
  16526.                      -x  Hex key.  The key string is a sequence of up
  16527.                          to 16 hex characters, right padded with
  16528.                          zeros.  With a hex key, the low order bit of
  16529.                          each byte is again ignored per the DES
  16530.                          algorithm.  This allows the use of any
  16531.                          arbitrary 56-bit key, including bytes
  16532.                          representing control characters that could
  16533.                          not be typed.
  16534.                      -h  Help.  (This screen.)
  16535.                      
  16536.                  Special Interchange Options:
  16537.  
  16538.  
  16539.  
  16540.                                      Page 260
  16541.  
  16542.                                                                          Help
  16543.  
  16544.  
  16545.                     Not all  DES implementations are the same.  There
  16546.                     are  a   number  of   early  implementations   in
  16547.                     circulation  that  either  poorly  or  improperly
  16548.                     implement DES.   Cipher Block Chaining may not be
  16549.                     supported, forcing the use of the -b option.  You
  16550.                     may also discover other flaws, necessitating that
  16551.                     you  experiment   with  some   of  these  special
  16552.                     options:
  16553.  
  16554.                      -n  Suppress parity calculation on an ascii key.
  16555.                          Just use the low-order 7 bits of each
  16556.                          character as-is.
  16557.                      -r  Convert all \r\n sequences to \n on input
  16558.                          and all \n characters to \r\n sequences on
  16559.                          output.  (Some implementors have used the C
  16560.                          library stdio read and write routines but
  16561.                          have forgotten to use binary mode.)
  16562.                      -z  Do not mark the last block with a length;
  16563.                          just fill it with binary zeros.  If you
  16564.                          encipher, then decipher a file this way, the
  16565.                          result will be padded with zeros out to an
  16566.                          8-byte boundary.
  16567.                      
  16568.                     If you  encounter problems  exchanging  encrypted
  16569.                     data with  another DES implementation, you should
  16570.                     try all  the various  combinations of the -b, -n,
  16571.                     -r and  -z options.   (We've  seen one  very poor
  16572.                     implementation of DES that had all these flaws.)
  16573.  
  16574.                  Notes:
  16575.  
  16576.                      1.  If you lose the key to a file encrypted with
  16577.                          DES, there  is no  known way  to decrypt it.
  16578.                          The data is lost.
  16579.  
  16580.                      2.  When choosing  keys, avoid  anything obvious
  16581.                          that someone else might easily guess.  E.g.,
  16582.                          don't use  just your  name or  your date  of
  16583.                          birth or  a common  word.  Instead, choose a
  16584.                          key  with   a  seemingly   random   mix   of
  16585.                          alphanumeric and punctuation characters.
  16586.  
  16587.                      3.  No encryption  system should  be  considered
  16588.                          perfectly secure.   Although  there  are  no
  16589.                          known practical  methods for  attacking DES,
  16590.                          such methods may exist.
  16591.  
  16592.                      4.  Encryption  can  only  protect  data  that's
  16593.                          actually encrypted.   If  you have copies of
  16594.                          the clear  text on  your disk,  anyone  with
  16595.                          access to  your machine  may be able to read
  16596.                          the  data.    Also,  even  when  a  file  is
  16597.                          deleted, the  contents may  remain  on  your
  16598.  
  16599.  
  16600.  
  16601.  
  16602.                                      Page 261
  16603.  
  16604.      Help
  16605.  
  16606.  
  16607.                          disk, accessible to anyone with knowledge of
  16608.                          the file system.
  16609.  
  16610.                      5.  If you  would  like  to  compress  encrypted
  16611.                          data, e.g.,  with utilities such as PKZip or
  16612.                          ARC, compress  first,  then  encrypt.    The
  16613.                          encryption  process  tends  to  destroy  the
  16614.                          redundancy  in  the  data  that  compression
  16615.                          programs depend on.
  16616.  
  16617.  
  16618.  
  16619.  
  16620.  
  16621.  
  16622.  
  16623.  
  16624.  
  16625.  
  16626.  
  16627.  
  16628.  
  16629.  
  16630.  
  16631.  
  16632.  
  16633.  
  16634.  
  16635.  
  16636.  
  16637.  
  16638.  
  16639.  
  16640.  
  16641.  
  16642.  
  16643.  
  16644.  
  16645.  
  16646.  
  16647.  
  16648.  
  16649.  
  16650.  
  16651.  
  16652.  
  16653.  
  16654.  
  16655.  
  16656.  
  16657.  
  16658.  
  16659.  
  16660.  
  16661.  
  16662.  
  16663.  
  16664.                                      Page 262
  16665.  
  16666.                                                                          Help
  16667.  
  16668.  
  16669.             diff:     Compare Files or Directories
  16670.  
  16671.                  Usage:  diff [-bBefhiqrvw!-] [-m minmatch] [-
  16672.                  Dstring] oldpath newpath
  16673.  
  16674.                     diff produces  a list  of differences between two
  16675.                     files or  directories.  The working assumption is
  16676.                     that newpath  is a newer version of whatever's in
  16677.                     oldpath.   If they're  files, diff  assumes  they
  16678.                     contain ascii  text but  if it  encounters a file
  16679.                     containing lots  of binary data, it switches to a
  16680.                     binary comparison mode to avoid dumping gibberish
  16681.                     to the screen.
  16682.  
  16683.                     Comparing files,  diff looks for minimal sections
  16684.                     of change.  Each difference  is shown  as an add,
  16685.                     delete  or   change  with  the  appropriate  line
  16686.                     numbers or  line number  ranges for   each  file.
  16687.                     Following are  texts of  the  differing  section.
  16688.                     Lines that  have been  deleted are  flagged  with
  16689.                     '<'; lines  that have been added are flagged with
  16690.                     '>'.   Alternately, diff  can be  used to produce
  16691.                     merged listings  with #ifdefs  for the C compiler
  16692.                     or highlighting for quick visual scanning.
  16693.  
  16694.                     Comparing directories,  the lists  of files  they
  16695.                     contain all  the way  down through  the tree  are
  16696.                     sorted, then  compared.   If  the  same  filename
  16697.                     exists in  each directory  tree, a  quick  binary
  16698.                     comparison is  normally made to give a quick yes-
  16699.                     or-no are  they different.   If  -r is specified,
  16700.                     the diff  text comparison is done recursively the
  16701.                     whole way down the two trees.
  16702.  
  16703.                     If one of the arguments to diff is a file and the
  16704.                     other is  a directory,  diff will  look  for  and
  16705.                     compare against  a file  of the  same name in the
  16706.                     directory.
  16707.  
  16708.                  Options:
  16709.  
  16710.                      -b  Blank spaces of any length compare equal.
  16711.                          Ignore any leading or trailing white space
  16712.                          on each line.
  16713.                      -B  Binary comparison even on text files.
  16714.                      -Dstring   Produce a merged #ifdef'ed listing,
  16715.                                 with the string being defined meaning
  16716.                                 use the older version. (Newer version
  16717.                                 is intentionally the default.)
  16718.                      -e  Turn off highlighting of empty lines.  Byt
  16719.                          default, if highlighting is used to show
  16720.                          areeas of change, even empty lines will have
  16721.                          Ansi sequences at the beginning and end so
  16722.                          that if more is used to display the output
  16723.  
  16724.  
  16725.  
  16726.                                      Page 263
  16727.  
  16728.      Help
  16729.  
  16730.  
  16731.                          with the default color stretch mode on,
  16732.                          empty lines will still be highlighted.
  16733.                      -f  Force diff-style comparison to continue even
  16734.                          on files that appear to contain binary data.
  16735.                      -i  Ignore character case.
  16736.                      -m minmatch     Minimum match length to insist
  16737.                                 on before resynchronizing two files.
  16738.                                 (Default is 2 lines.)
  16739.                      -q  Quiet:  supress warnings about files
  16740.                          containing binary data.
  16741.                      -r  Recursively diff the contents of any
  16742.                          subdirectories.
  16743.                      -v  Verbose listing of all the contents of any
  16744.                          entire subdirectory added or deleted.
  16745.                      -h  Help.  (This screen.)
  16746.                      -w  White space is ignored totally.
  16747.                      -!  Produce merged, highlighted version.  Text
  16748.                          that's unchanged is normal, deleted text is
  16749.                          red, new text is green.
  16750.                      --  End of options.
  16751.                      
  16752.                  Colors:
  16753.  
  16754.                     You may  set your  own choices  for screen colors
  16755.                     using these environmental variables:
  16756.  
  16757.                     Name          Use                    Default
  16758.  
  16759.                     COLORS        Normal screen colors   White on
  16760.                     Black
  16761.                     ADDITIONS     Lines added            Bright Green
  16762.                     DELETIONS     Lines deleted          Bright Red
  16763.  
  16764.                     Colors recognized  are black, red, green, yellow,
  16765.                     blue, magenta (or red blue), cyan (or blue green)
  16766.                     or white.   Foreground  colors may also be bright
  16767.                     or blink.   The names of the colors and the words
  16768.                     bright, blink  and on  may be  in either upper or
  16769.                     lower  or   mixed  case  but  the  names  of  the
  16770.                     environmental variables  themselves must  be  all
  16771.                     upper case.
  16772.  
  16773.                     Either or  both  the  foreground  and  background
  16774.                     colors may  be specified;  if you don't specify a
  16775.                     value, it's  considered transparent  and inherits
  16776.                     the  color   underneath  it.       ADDITIONS  and
  16777.                     DELETIONS inherit from COLORS.
  16778.  
  16779.  
  16780.  
  16781.  
  16782.  
  16783.  
  16784.  
  16785.  
  16786.  
  16787.  
  16788.                                      Page 264
  16789.  
  16790.                                                                          Help
  16791.  
  16792.  
  16793.             dim:      Discard any ansi escape sequences in the input
  16794.             stream
  16795.  
  16796.                  Usage:  dim [-h-] [ file1 file2 ... ]
  16797.  
  16798.                     dim deletes  any  ansi  escape  sequences  as  it
  16799.                     copies text  from each  of the  files you specify
  16800.                     onto stdout.  If several files are given, they're
  16801.                     concatenated one after another to the output.
  16802.  
  16803.                     If no files are given, dim reads from stdin.
  16804.  
  16805.                  Options:
  16806.  
  16807.                      -h  Help.  (This screen.)
  16808.                      --  End of options.
  16809.  
  16810.  
  16811.             dirs:     List the Current Directory Stack
  16812.  
  16813.                  Usage:  dirs [-h-]
  16814.  
  16815.                     Show  the   list  of   fully-qualified  directory
  16816.                     pathnames  on   the  current   directory   stack,
  16817.                     highlighting the current disk:directory pair.
  16818.  
  16819.                     Hamilton C  shell maintains  a stack representing
  16820.                     the current  directory and  any previous  current
  16821.                     directories has saved there.
  16822.  
  16823.                     (See also the cd, pushd, popd and rotd commands.)
  16824.  
  16825.                  Options:
  16826.  
  16827.                      -h  Help.
  16828.                      --  End of options.
  16829.  
  16830.  
  16831.  
  16832.  
  16833.  
  16834.  
  16835.  
  16836.  
  16837.  
  16838.  
  16839.  
  16840.  
  16841.  
  16842.  
  16843.  
  16844.  
  16845.  
  16846.  
  16847.  
  16848.  
  16849.  
  16850.                                      Page 265
  16851.  
  16852.      Help
  16853.  
  16854.  
  16855.             dskread:  Read Raw Sectors from a Disk
  16856.  
  16857.                  Usage:  dskread [-bcdhHL-] [-n name] [-N sectors] [-
  16858.                  s size] [-t tracks]
  16859.                            [ disk: ] [ <sectorlist> ]
  16860.  
  16861.                     dskread copies  low-level raw sectors on the disk
  16862.                     you specify to stdout.
  16863.  
  16864.                     In conjunction  with dskwrite,  dskread  is  most
  16865.                     useful as  a quick  diskette duplication utility:
  16866.                     you can  read a  whole diskette image into a file
  16867.                     with  dskread,   then  write  it  back  out  with
  16868.                     dskwrite to a new diskette.  But it's also useful
  16869.                     for restoring a long stream of data dumped across
  16870.                     a series of diskettes with dskwrite.
  16871.  
  16872.                     The disk  is given as a a single alphabetic drive
  16873.                     letter plus  a colon.   If  no disk is specified,
  16874.                     the first  logical  drive  is  assumed  (in  most
  16875.                     machines, this is the a: drive).
  16876.  
  16877.                  Operation:
  16878.  
  16879.                     dskread normally  starts at  cylinder 0,  head 0,
  16880.                     sector  0  and  walks  through  the  whole  disk,
  16881.                     reading all the sectors on a track under one head
  16882.                     and  then   all  tracks   in  a  cylinder  before
  16883.                     repositioning the heads to the next cylinder.
  16884.  
  16885.                     dskread always  reads whole  sectors except  when
  16886.                     reading from a file using the -d option.
  16887.  
  16888.                  Options:
  16889.  
  16890.                      -b  Boot record.  Skip sector 0 on the
  16891.                          assumption it simply contains a standard
  16892.                          boot record and parameter block
  16893.                          corresponding to the particular media.
  16894.                      -c  Continuation.  Assume the data has been
  16895.                          split across several diskettes.  After each
  16896.                          disk has been read, prompt for the next one.
  16897.                          If -d is specified also, the filename
  16898.                          extension on each disk will be the disk
  16899.                          number, i.e., 001, 002, 003, etc.
  16900.                      -d  Dummy filesystem.  Assume the data is in a
  16901.                          single file on the disk.  If neither the -d
  16902.                          nor the -b options is given, the disk will
  16903.                          be read beginning with sector 0.
  16904.                      -h  Help.  (This screen.)
  16905.                      -n <name>  The filename to look for if the -d
  16906.                                 (dummy file- system) option is used.
  16907.                                 Default is `bindata'.
  16908.                      --  End of options.
  16909.  
  16910.  
  16911.  
  16912.                                      Page 266
  16913.  
  16914.                                                                          Help
  16915.  
  16916.  
  16917.                  Formatting:
  16918.  
  16919.                     Default is  to let  OS/2 or  Windows  NT  try  to
  16920.                     determine the  formatting that  was used.  If the
  16921.                     disk was  written in  unusual format  or has non-
  16922.                     standard data  in sector 0, the following options
  16923.                     can be  override OS/2  or Windows NT's attempt to
  16924.                     guess the format:
  16925.  
  16926.                      -H  High density formatting.
  16927.                      -L  Low density formatting.
  16928.                      -N <sectors>    Sectors per track.
  16929.                      -s <size>  Sector size.  Normally only 512 is
  16930.                                 supported but, depending on your
  16931.                                 hardware, you may also be able to
  16932.                                 create 128, 256 or 1024-byte sectors.
  16933.                      -t <tracks>     Number of tracks.
  16934.                      
  16935.                  Sector lists:
  16936.  
  16937.                     Optionally, you can specify a list of sectors you
  16938.                     want written. Sectors are given in
  16939.  
  16940.                         (cylinder, head, sector)
  16941.  
  16942.                     coordinates with parentheses around and commas or
  16943.                     white space  to separate  the numeric  values you
  16944.                     write.   Cylinders, heads and sectors are counted
  16945.                     from zero and can be specified in decimal, hex or
  16946.                     octal.
  16947.  
  16948.                     A single  sector specified  alone means just that
  16949.                     sector. Listing  several separated  by commas  or
  16950.                     spaces means each one individually.
  16951.  
  16952.                     A pair  of sectors  joined by  a hyphen  means  a
  16953.                     range:   all the  consecutive  sectors  beginning
  16954.                     with the first and running through to the second.
  16955.  
  16956.                     Specifying a negative number as an ordinate means
  16957.                     use the highest possible value for that disk.
  16958.  
  16959.                     If any  of the ordinates of a sector are omitted,
  16960.                     they're assumed to be zero exept when it closes a
  16961.                     range, in  which case  it means  use the  highest
  16962.                     possible value.
  16963.  
  16964.                  Examples:
  16965.  
  16966.                      1.  To  duplicate   a  whole   diskette   image,
  16967.                          autoformatting the  output media if it's not
  16968.                          already formatted:
  16969.  
  16970.  
  16971.  
  16972.  
  16973.  
  16974.                                      Page 267
  16975.  
  16976.      Help
  16977.  
  16978.  
  16979.                            % dskread a: > dskimage.a
  16980.                            % dskwrite -av a: < dskimage.a
  16981.  
  16982.                      2.  To use a diskette as a serial archive media:
  16983.                          The -d  option allows  you to  request  just
  16984.                          enough dummy file system ``envelope'' around
  16985.                          the otherwise  arbitrary data  you intend to
  16986.                          write to  ensure the  disk can still be used
  16987.                          with other  OS/2 or  Windows  NT  utilities.
  16988.                          Here's an  example writing  the result  of a
  16989.                          tar'ing (archiving)  a whole  directory to a
  16990.                          series of diskettes, again autoformatting:
  16991.  
  16992.                            % tar -asr mydir < nul | dskwrite -avcd -n
  16993.                         mydir a:
  16994.  
  16995.                          It's restored with
  16996.  
  16997.                            % dskread -dc -n mydir a: | tar -xsr
  16998.  
  16999.                          The diskettes used do not all have to be the
  17000.                          same density;  any mix  of high  and low  is
  17001.                          okay.   But remember  that if  a disk  isn't
  17002.                          already  formatted,   there's  no   way  for
  17003.                          dskwrite to  tell whether  it should be high
  17004.                          or low  density; any  disks it has to format
  17005.                          will all be formatted the same way.
  17006.  
  17007.                          If putting  the greatest  possible amount of
  17008.                          data on  a diskette  is more  important than
  17009.                          compatibility with  other OS/2 or Windows NT
  17010.                          utilities,  you   can  also  use  the  space
  17011.                          normally devoted  to the FAT file system and
  17012.                          even the boot sector.  Here is the same tar,
  17013.                          written  to   a  series   of   autoformatted
  17014.                          high-density diskettes where every sector is
  17015.                          used for data:
  17016.  
  17017.                            % tar -asr mydir < nul | dskwrite -avcHx
  17018.                         a:
  17019.  
  17020.                          It's restored with
  17021.  
  17022.                            % dskread -cH a: | tar -xsr
  17023.  
  17024.                          Since no  labeling of the data is written to
  17025.                          the diskette, it's the user's responsibility
  17026.                          to   keep track  of the  order in  which the
  17027.                          disks were  written and even what format was
  17028.                          used.
  17029.  
  17030.  
  17031.  
  17032.  
  17033.  
  17034.  
  17035.  
  17036.                                      Page 268
  17037.  
  17038.                                                                          Help
  17039.  
  17040.  
  17041.             dskwrite: Write Raw Sectors to a Disk
  17042.  
  17043.                  Usage:  dskwrite [-abcdfFhHLTvxz-] [-Z!] [-n name]
  17044.                  [-N sectors] [-s size] [-t tracks]
  17045.                            [-V volid] [ disk: ] [ <sectorlist> ]
  17046.  
  17047.                     dskwrite  copies   stdin  to  the  low-level  raw
  17048.                     sectors on the disk you specify.
  17049.  
  17050.                     In conjunction  with dskread,  dskwrite  is  most
  17051.                     useful as  a quick  diskette duplication utility:
  17052.                     you can  read a  whole diskette image into a file
  17053.                     with  dskread,   then  write  it  back  out  with
  17054.                     dskwrite to a new diskette.  But it's also useful
  17055.                     for dumping a long stream of data across a series
  17056.                     of diskettes, formatting and filling each as much
  17057.                     as possible before requesting the next one.
  17058.  
  17059.                     The disk  is given as a a single alphabetic drive
  17060.                     letter plus  a colon.   If  no disk is specified,
  17061.                     the first  logical drive  is assumed.   (In  most
  17062.                     machines, this is the a: drive.)
  17063.  
  17064.                  Operation:
  17065.  
  17066.                     dskwrite normally  starts at  cylinder 0, head 0,
  17067.                     sector  0  and  walks  through  the  whole  disk,
  17068.                     writing all the sectors on a track under one head
  17069.                     and  then   all  tracks   in  a  cylinder  before
  17070.                     repositioning the  heads to  the  next  cylinder.
  17071.                     You can  also cause  dskwrite to  write  to  just
  17072.                     specific sectors by giving it a sector list.
  17073.  
  17074.                     dskwrite always  writes  whole  sectors  and,  if
  17075.                     requested, formats  whole tracks.   If  the  last
  17076.                     sector is  only partially-used, dskwrite fills it
  17077.                     out with binary zeros.
  17078.  
  17079.                     To  avoid   conflicts  with  other  applications,
  17080.                     dskwrite always  locks a  drive  before  actually
  17081.                     writing to it.
  17082.  
  17083.                  Basic Options:
  17084.  
  17085.                      -a  Autoformat.  If the disk appears to be
  17086.                          unformatted, automatically do a low-level
  17087.                          format of the entire disk.
  17088.                      -f  Low-level format the entire disk as data is
  17089.                          copied to it from stdin.
  17090.                      -F  Low-level format the entire disk and create
  17091.                          an empty FAT filesystem.  Do not read
  17092.                          anything from stdin.
  17093.                      -v  Verify.  Read back and verify each write.
  17094.                      -h  Help.  (This screen.)
  17095.  
  17096.  
  17097.  
  17098.                                      Page 269
  17099.  
  17100.      Help
  17101.  
  17102.  
  17103.                      --  End of options.
  17104.  
  17105.  
  17106.  
  17107.  
  17108.  
  17109.  
  17110.  
  17111.  
  17112.  
  17113.  
  17114.  
  17115.  
  17116.  
  17117.  
  17118.  
  17119.  
  17120.  
  17121.  
  17122.  
  17123.  
  17124.  
  17125.  
  17126.  
  17127.  
  17128.  
  17129.  
  17130.  
  17131.  
  17132.  
  17133.  
  17134.  
  17135.  
  17136.  
  17137.  
  17138.  
  17139.  
  17140.  
  17141.  
  17142.  
  17143.  
  17144.  
  17145.  
  17146.  
  17147.  
  17148.  
  17149.  
  17150.  
  17151.  
  17152.  
  17153.  
  17154.  
  17155.  
  17156.  
  17157.  
  17158.  
  17159.  
  17160.                                      Page 270
  17161.  
  17162.                                                                          Help
  17163.  
  17164.  
  17165.                  Options for using the disk as a serial media:
  17166.  
  17167.                      -b  Boot record.  Write a simple non-system disk
  17168.                          boot record and parameter block
  17169.                          corresponding to the particular media into
  17170.                          sector 0.  If writing the entire disk,
  17171.                          continue with the next sector.
  17172.                      -c  Continuation.  If there's more data on stdin
  17173.                          after an entire disk has been written,
  17174.                          prompt for a new disk to be inserted and
  17175.                          continue.  If -d is specified also, the
  17176.                          filename extension on each disk will be the
  17177.                          disk number, i.e., 001, 002, 003, etc.
  17178.                      -d  Dummy filesystem.  Write a boot record and a
  17179.                          FAT filesystem into the initial sectors
  17180.                          allocating whatever is written to a single
  17181.                          file.
  17182.                      -n <name>  The filename to be given to any data
  17183.                                 written onto the disk if the -d
  17184.                                 (dummy filesystem) option is used.
  17185.                                 Default is 'bindata'.
  17186.                      
  17187.                  Formatting:
  17188.  
  17189.                     Default is  to let  OS/2 or  Windows  NT  try  to
  17190.                     determine how  the media  has been  formatted and
  17191.                     not to reformat the disk.
  17192.  
  17193.                     If the  disk isn't  already formatted  and the -a
  17194.                     (autoformat) option  is selected or if formatting
  17195.                     is  explicitly   requested  with  the  -f  or  -F
  17196.                     options, dskwrite  will do  a low-level format of
  17197.                     the media.
  17198.  
  17199.                     dskwrite takes  its specification  of the  format
  17200.                     (e.g., low-  or high-density)  from the following
  17201.                     sources, in decreasing priority:
  17202.  
  17203.                      1.  Explicit specifications on the command line.
  17204.                      2.  The OS/2 or Windows NT kernel's guess at the
  17205.                          media format, assuming the disk is already
  17206.                          formatted and not being re-formatted.
  17207.                      3.  The format parameters in the boot sector
  17208.                          copied from stdin, assuming neither the -b
  17209.                          nor the -d options is given.
  17210.                      4.  The previous format of the media, assuming
  17211.                          it's already formatted in a standard
  17212.                          configuration but being reformatted.
  17213.                      5.  The highest-density format supported by the
  17214.                          drive.
  17215.                      
  17216.                     Unless you specify -b or -d, dskwrite will expect
  17217.                     to  copy  a  compatible  disk  image  from  stdin
  17218.                     including a  suitable boot  sector,  etc.    That
  17219.  
  17220.  
  17221.  
  17222.                                      Page 271
  17223.  
  17224.      Help
  17225.  
  17226.  
  17227.                     happens automatically  when dskread'ing  a  whole
  17228.                     disk is paired with dskwrite'ing a whole disk but
  17229.                     not otherwise.
  17230.  
  17231.  
  17232.  
  17233.  
  17234.  
  17235.  
  17236.  
  17237.  
  17238.  
  17239.  
  17240.  
  17241.  
  17242.  
  17243.  
  17244.  
  17245.  
  17246.  
  17247.  
  17248.  
  17249.  
  17250.  
  17251.  
  17252.  
  17253.  
  17254.  
  17255.  
  17256.  
  17257.  
  17258.  
  17259.  
  17260.  
  17261.  
  17262.  
  17263.  
  17264.  
  17265.  
  17266.  
  17267.  
  17268.  
  17269.  
  17270.  
  17271.  
  17272.  
  17273.  
  17274.  
  17275.  
  17276.  
  17277.  
  17278.  
  17279.  
  17280.  
  17281.  
  17282.  
  17283.  
  17284.                                      Page 272
  17285.  
  17286.                                                                          Help
  17287.  
  17288.  
  17289.                  Explicit Format Specification Options:
  17290.  
  17291.                      -H  High density format.
  17292.                      -L  Low density format.
  17293.                      -N <sectors>    Sectors per track.
  17294.                      -s <size>  Sector size.  Normally only 512 is
  17295.                                 supported but, depending on your
  17296.                                 hardware, you may also be able to
  17297.                                 create 128, 256 or 1024-byte sectors.
  17298.                      -t <tracks>     Number of tracks.
  17299.                      
  17300.                     Other Advanced Options:
  17301.  
  17302.                      -T  Low-level format the media track-at-a-time
  17303.                          as the disk is written.  Only as much of the
  17304.                          disk as is being written to will be
  17305.                          formatted.
  17306.                      -V <volid> The volume identifier to be written
  17307.                                 into the dummy filesystem header if
  17308.                                 -F or -d is used.  (Ignored
  17309.                                 otherwise.)
  17310.                      -x  Force use of a non-standard format or
  17311.                          writing of non-standard format parameters to
  17312.                          the boot sector.
  17313.                      -z  Zero-length files written with -d option
  17314.                          should still be added to the directory.
  17315.                          (Otherwise, they're ignored.)
  17316.                      -Z! Force write to a hard disk.  Warning! Very
  17317.                          risky unless you know exactly what you're
  17318.                          doing.
  17319.                      
  17320.                  Sector lists:
  17321.  
  17322.                     Optionally, you can specify a list of sectors you
  17323.                     want written. Sectors are given in
  17324.  
  17325.                         (cylinder, head, sector)
  17326.  
  17327.                     coordinates with parentheses around and commas or
  17328.                     white space  to separate  the numeric  values you
  17329.                     write.   Cylinders, heads and sectors are counted
  17330.                     from zero and can be specified in decimal, hex or
  17331.                     octal.
  17332.  
  17333.                     A single  sector specified  alone means just that
  17334.                     sector. Listing  several separated  by commas  or
  17335.                     spaces means each one individually.
  17336.  
  17337.                     A pair  of sectors  joined by  a hyphen  means  a
  17338.                     range:   all the  consecutive  sectors  beginning
  17339.                     with the first and running through to the second.
  17340.  
  17341.                     Specifying a negative number as an ordinate means
  17342.                     use the highest possible value for that disk.
  17343.  
  17344.  
  17345.  
  17346.                                      Page 273
  17347.  
  17348.      Help
  17349.  
  17350.  
  17351.                     If any  of the ordinates of a sector are omitted,
  17352.                     they're assumed to be zero exept when it closes a
  17353.                     range, in  which case  it means  use the  highest
  17354.                     possible value.
  17355.  
  17356.                  Examples:
  17357.  
  17358.                      1.  To  duplicate   a  whole   diskette   image,
  17359.                          autoformatting the  output media if it's not
  17360.                          already formatted:
  17361.  
  17362.                            % dskread a: > dskimage.a
  17363.                            % dskwrite -av a: < dskimage.a
  17364.  
  17365.                      2.  To use  dskwrite to  format a  disk with  an
  17366.                          empty FAT file system, use either:
  17367.  
  17368.                            % dskwrite -F a:
  17369.  
  17370.                          or:
  17371.  
  17372.                            % dskwrite -df a: <nul
  17373.  
  17374.                      3.  To rewrite just the boot sector to make it a
  17375.                          non-system disk:
  17376.  
  17377.                            % dskwrite -b a: <nul
  17378.  
  17379.                      4.  To use a diskette as a serial archive media:
  17380.  
  17381.                          The -d  option allows  you to  request  just
  17382.                          enough dummy file system ``envelope'' around
  17383.                          the otherwise  arbitrary data  you intend to
  17384.                          write to  ensure the  disk can still be used
  17385.                          with other  OS/2 or  Windows  NT  utilities.
  17386.                          Here's an  example writing  the result  of a
  17387.                          tar'ing (archiving)  a whole  directory to a
  17388.                          series of diskettes, again autoformatting:
  17389.  
  17390.                            % tar -asr mydir < nul | dskwrite -avcd -n
  17391.                         mydir a:
  17392.  
  17393.                          It's restored with
  17394.  
  17395.                            % dskread -dc -n mydir a: | tar -xsr
  17396.  
  17397.                          The diskettes used do not all have to be the
  17398.                          same density;  any mix  of high  and low  is
  17399.                          okay.   But remember  that if  a disk  isn't
  17400.                          already  formatted,   there's  no   way  for
  17401.                          dskwrite to  tell whether  it should be high
  17402.                          or low  density; any  disks it has to format
  17403.                          will all be formatted the same way.
  17404.  
  17405.  
  17406.  
  17407.  
  17408.                                      Page 274
  17409.  
  17410.                                                                          Help
  17411.  
  17412.  
  17413.                          If putting  the greatest  possible amount of
  17414.                          data on  a diskette  is more  important than
  17415.                          compatibility with  other OS/2 or Windows NT
  17416.                          utilities,  you   can  also  use  the  space
  17417.                          normally devoted  to the FAT file system and
  17418.                          even the boot sector.  Here is the same tar,
  17419.                          written to  a series  of autoformatted high-
  17420.                          density diskettes where every sector is used
  17421.                          for data:
  17422.  
  17423.                            % tar -asr mydir < nul | dskwrite -avcHx
  17424.                         a:
  17425.  
  17426.                          It's restored with
  17427.  
  17428.                            % dskread -cH a: | tar -xsr
  17429.  
  17430.                          Since no  labeling of the data is written to
  17431.                          the diskette, it's the user's responsibility
  17432.                          to   keep track  of the  order in  which the
  17433.                          disks were  written and even what format was
  17434.                          used.
  17435.  
  17436.                  Non-standard Diskette Formats:
  17437.  
  17438.                     If you  write anything but a standard boot record
  17439.                     into the  boot sector,  you will  not be  able to
  17440.                     read it  with anything  but dskread and even then
  17441.                     only if  you tell  it explicitly what what format
  17442.                     was used.   Without a standard parameter block in
  17443.                     the boot  sector, the  the OS/2  and  Windows  NT
  17444.                     diskette device  drivers just  can't tell  on its
  17445.                     own how the diskette was written.
  17446.  
  17447.                     Similarly, it's possible you may be able to write
  17448.                     a non-standard  format (e.g., a sector size other
  17449.                     than 512 bytes, etc.) depending on your hardware.
  17450.                     But doing  that may  make the diskette impossible
  17451.                     to read on other machines.
  17452.  
  17453.                     For that  reason, dskwrite normally won't let you
  17454.                     write a boot record that doesn't match the actual
  17455.                     format of  the diskette nor will it let you write
  17456.                     anything other  than one  of the standard format.
  17457.                     To override  these checks,  you must  use the  -x
  17458.                     option.
  17459.  
  17460.                  Writing to a Hard Disk:
  17461.  
  17462.                     Deliberately, dskwrite  normally  only  lets  you
  17463.                     write to diskettes.
  17464.  
  17465.                     Writing to  a hard  disk is  very risky since the
  17466.                     chance of  catastrophic loss of information is so
  17467.  
  17468.  
  17469.  
  17470.                                      Page 275
  17471.  
  17472.      Help
  17473.  
  17474.  
  17475.                     high.   Also, only ESDI and SCSI disk controllers
  17476.                     routinely map out bad blocks, so reading the disk
  17477.                     image from one drive and writing it to another is
  17478.                     unlikely to  work if  there  are  bad  blocks  on
  17479.                     either one.
  17480.  
  17481.                     To force  dskwrite to  write to  a hard disk, you
  17482.                     must specify  the -Z! option, meant to be hard to
  17483.                     accidentally type.     In effect,  the -Z! option
  17484.                     means you understand the risk you're taking.
  17485.  
  17486.  
  17487.  
  17488.  
  17489.  
  17490.  
  17491.  
  17492.  
  17493.  
  17494.  
  17495.  
  17496.  
  17497.  
  17498.  
  17499.  
  17500.  
  17501.  
  17502.  
  17503.  
  17504.  
  17505.  
  17506.  
  17507.  
  17508.  
  17509.  
  17510.  
  17511.  
  17512.  
  17513.  
  17514.  
  17515.  
  17516.  
  17517.  
  17518.  
  17519.  
  17520.  
  17521.  
  17522.  
  17523.  
  17524.  
  17525.  
  17526.  
  17527.  
  17528.  
  17529.  
  17530.  
  17531.  
  17532.                                      Page 276
  17533.  
  17534.                                                                          Help
  17535.  
  17536.  
  17537.             du:       List Disk Usage Statistics
  17538.  
  17539.                  Usage:  du [-acdxvh] [ disk1 disk2 ... ]
  17540.  
  17541.                     du prints  statistics showing the total, used and
  17542.                     free space  on each  disk partition.  If no disks
  17543.                     are  specified,   du  looks   for   a   DRIVEMASK
  17544.                     environmental variable  that can  be used to mask
  17545.                     off just  the  drive  you  want  reported.    The
  17546.                     DRIVEMASK  is   specified  as  a  list  of  drive
  17547.                     letters; ranges  are allowed.  Otherwise, all the
  17548.                     fixed  disk  partitions  beginning  with  c:  are
  17549.                     reported.   The  current  disk's  statistics  are
  17550.                     highlighted.   Sizes  are  normally  reported  in
  17551.                     binary (1000*1024) megabytes.
  17552.  
  17553.                  Option:
  17554.  
  17555.                      -a  If no disks are specified, report on all
  17556.                          disks.
  17557.                      -c  If no disks are specified, report on just
  17558.                          the current disk.
  17559.                      -d  Report in decimal (1,000,000) megabytes.
  17560.                      -x  Report in hex (1024*1024) megabytes.
  17561.                      -v  Give detailed cluster information.
  17562.                      -h  Help.
  17563.                      --  End of options.
  17564.                      
  17565.                     Name          Use                    Default
  17566.  
  17567.                     COLORS        Normal screen colors   White on
  17568.                     Black
  17569.                     HIGHLIGHT     Current disk or directory.  Bright
  17570.  
  17571.                     Colors recognized  are black, red, green, yellow,
  17572.                     blue, magenta (or red blue), cyan (or blue green)
  17573.                     or white.   Foreground  colors may also be bright
  17574.                     or blink.   The names of the colors and the words
  17575.                     bright, blink  and on  may be  in either upper or
  17576.                     lower  or   mixed  case  but  the  names  of  the
  17577.                     environmental variables  themselves must  be  all
  17578.                     upper case.
  17579.  
  17580.                     Either or  both  the  foreground  and  background
  17581.                     colors may  be specified;  if you don't specify a
  17582.                     value, it's  considered transparent  and inherits
  17583.                     the color  underneath it.     HIGHLIGHT  inherits
  17584.                     from COLORS.
  17585.  
  17586.  
  17587.  
  17588.  
  17589.  
  17590.  
  17591.  
  17592.  
  17593.  
  17594.                                      Page 277
  17595.  
  17596.      Help
  17597.  
  17598.  
  17599.             echo:     Echo the Arguments to Standard Output
  17600.  
  17601.                  Usage:  echo [-n2h-] [ text ]
  17602.  
  17603.                     Echo the  text to  standard output  (or  stderr),
  17604.                     substituting  for   certain  character  sequences
  17605.                     preceded  by   the  escapesym   character.   (The
  17606.                     escapesym character  is normally  `^' but  can be
  17607.                     changed with the set command.)
  17608.  
  17609.                        ^a  Audible Alert (Bell)   ^r  Carriage Return
  17610.                        ^b  BackSpace              ^t  Tab
  17611.                        ^f  Form Feed              ^v  Vertical Tab
  17612.                        ^n  NewLine                ^^  Single
  17613.                     escapesym
  17614.  
  17615.                     The escapesym character may also be followed with
  17616.                     the numeric  value of  the intended  substitution
  17617.                     character where the value is specified in hex (as
  17618.                     an 'x' followed by hex digits) or in octal.
  17619.  
  17620.                  Options:
  17621.  
  17622.                      -n  Don't automatically append a Carriage
  17623.                          Return/Line Feed sequence to the end of the
  17624.                          output.
  17625.                      -2  Write to stderr instead of stdout.
  17626.                      -h  Help.
  17627.                      --  End of options.
  17628.  
  17629.  
  17630.  
  17631.  
  17632.  
  17633.  
  17634.  
  17635.  
  17636.  
  17637.  
  17638.  
  17639.  
  17640.  
  17641.  
  17642.  
  17643.  
  17644.  
  17645.  
  17646.  
  17647.  
  17648.  
  17649.  
  17650.  
  17651.  
  17652.  
  17653.  
  17654.  
  17655.  
  17656.                                      Page 278
  17657.  
  17658.                                                                          Help
  17659.  
  17660.  
  17661.             eval:     Parse & Evaluate at Run-Time
  17662.  
  17663.                  Usage:  eval [delta] [-irfth-] [ argument words ]
  17664.  
  17665.                     Evaluate the  words following on the command line
  17666.                     as text  to be parsed and evaluated as statements
  17667.                     only after  all the substitutions and wildcarding
  17668.                     have been  done.   Optionally, under  OS/2,  eval
  17669.                     lets you  run the  command at  a higher  or lower
  17670.                     scheduling priority.
  17671.  
  17672.                     Command or variable substitutions aren't normally
  17673.                     done until  after statements  have  already  been
  17674.                     parsed and compiled into an internal form and, if
  17675.                     it's a  background statement,  passed  off  to  a
  17676.                     background child thread.
  17677.  
  17678.                     The eval command is useful if either:
  17679.  
  17680.                      -   You want command or variable substitutions
  17681.                          to be recognized as any of the reserved
  17682.                          words of the language or as an alias, or
  17683.                      -   You want the substitutions done before a
  17684.                          background thread is started, or
  17685.                      -   You want to run the command at a different
  17686.                          priority.
  17687.  
  17688.                  Options:
  17689.  
  17690.                      -i  Idle time priority.  (In Unix terms, this is
  17691.                          the ``nice'' option:  if you're nice, you
  17692.                          run at idle priority and let everything else
  17693.                          run ahead of you.)
  17694.                      -r  Regular priority.  (The usual initial
  17695.                          value.)
  17696.                      -f  Foreground priority.
  17697.                      -t  Time critical priority.
  17698.                      delta      A signed integer amount by which the
  17699.                                 scheduling priority for this command
  17700.                                 is to be adjusted up or down.  The
  17701.                                 `+' or `-' sign is required to
  17702.                                 distinguish this as an option.
  17703.                                 Priority ranges from 0 to 31 and is
  17704.                                 normally 0 when the C shell starts up
  17705.                                 or if a new priority class is chosen.
  17706.                                 Attempting to set priority below 0 or
  17707.                                 above the maximum results in priority
  17708.                                 0 or 31 respectively.
  17709.                      -h  Help.
  17710.                      --  End of options.
  17711.  
  17712.  
  17713.  
  17714.  
  17715.  
  17716.  
  17717.  
  17718.                                      Page 279
  17719.  
  17720.      Help
  17721.  
  17722.  
  17723.             fgrep:    Fast string search (fast grep) of text files
  17724.  
  17725.                  Usage:  fgrep [-hbcilnqsvwx-] [-f ptrnfile] [
  17726.                  pattern ] [ file1 file2 ...]
  17727.  
  17728.                     fgrep does  a quick,  deliberately simple  string
  17729.                     search.  It does not use regular expressions, but
  17730.                     does have  some diff-style  options for  ignoring
  17731.                     upper-/lower-case differences  or treating  white
  17732.                     spaces of any length as equal, etc.  You can also
  17733.                     give it  a list of strings you want searched for,
  17734.                     one per line in a pattern file or via stdin.
  17735.  
  17736.                     Each matching  line is copied to stdout.  If more
  17737.                     than one  file is  being searched,  each line  is
  17738.                     preceded by  the name  of file  where  the  match
  17739.                     occurred plus a `:' character.
  17740.  
  17741.                  Options:
  17742.  
  17743.                      -h  Help.  (This screen.)
  17744.                      -b  Blank spaces of any length compare equal.
  17745.                          Ignore any leading or trailing white space
  17746.                          on each line.
  17747.                      -c  Just print a count of the number of lines
  17748.                          which match.
  17749.                      -f ptrnfile  Read the patterns from a file.
  17750.                      -i  Ignore character case.
  17751.                      -l  Show just the names of any files containing
  17752.                          at least one match.  Show each name only
  17753.                          once, each on a separate line.
  17754.                      -n  Show the line numbers of any matches.
  17755.                      -q  Quiet:  don't show filenames where the
  17756.                          matches occur.
  17757.                      -s  Read the patterns from stdin.
  17758.                      -v  Invert the pattern:  show all lines except
  17759.                          those that match.
  17760.                      -w  White space is ignored totally.
  17761.                      -x  Exact match:  the whole line must match the
  17762.                          pattern.
  17763.                      --  End of options.
  17764.  
  17765.  
  17766.  
  17767.  
  17768.  
  17769.  
  17770.  
  17771.  
  17772.  
  17773.  
  17774.  
  17775.  
  17776.  
  17777.  
  17778.  
  17779.  
  17780.                                      Page 280
  17781.  
  17782.                                                                          Help
  17783.  
  17784.  
  17785.             grep:     Regular expression pattern search of text files
  17786.  
  17787.                  Usage:  grep [-hcilnqsv-] [-f ptrnfile] [ pattern ]
  17788.                  [ file1 file2 ...]
  17789.  
  17790.                     grep  uses   special  patterns   called   regular
  17791.                     expressions to filter what it reads from stdin or
  17792.                     from any files you specify.
  17793.  
  17794.                     Regular expressions are written in this notation,
  17795.                     in decreasing precedence:
  17796.  
  17797.                      c          Any ordinary character matches
  17798.                                 itself.
  17799.                      \c         Match the literal character c.
  17800.                      ^          Beginning of line.
  17801.                      $          End of line.
  17802.                      .          Match any single character.
  17803.                      [...]      Match any single character in the
  17804.                                 list.
  17805.                      [^...]     Match any single character not in the
  17806.                                 list.
  17807.                      \n         Match whatever literal text the n'th
  17808.                                 tagged \(...\) expression matched.
  17809.                      r*         Match zero or more occurrences of r.
  17810.                      r1r2       Match expression r1 followed by r2.
  17811.                      \(r\)      Tagged regular expression.  Match the
  17812.                                 pattern inside the \(...\), and
  17813.                                 remember the literal text that
  17814.                                 matched.
  17815.                      
  17816.                     A regular expression pattern cannot contain Null,
  17817.                     NewLine or CarriageReturn characters.
  17818.  
  17819.                     When typing  a regular  expression on the command
  17820.                     line, remember  that $,  [, ],  ^, (  and )  have
  17821.                     special meaning  to Hamilton  C shell. Put single
  17822.                     quotes around the string to turn off that special
  17823.                     meaning.   Also, even  inside quotes,  type ^^ to
  17824.                     mean ^ except when it immediately follows [.
  17825.  
  17826.                     Each matching  line is copied to stdout.  If more
  17827.                     than one  file is  being searched,  each line  is
  17828.                     preceded by  the name  of file  where the matched
  17829.                     occurred plus a `:' character.
  17830.  
  17831.                  Options:
  17832.  
  17833.                      -h  Help.  (This screen.)
  17834.                      -c  Just print a count of the number of lines
  17835.                          which match.
  17836.                      -f ptrnfile     Read the patterns from a file.
  17837.                      -i  Ignore character case.
  17838.  
  17839.  
  17840.  
  17841.  
  17842.                                      Page 281
  17843.  
  17844.      Help
  17845.  
  17846.  
  17847.                      -l  Show just the names of any files containing
  17848.                          at least one match.  Show each name only
  17849.                          once, each on a separate line.
  17850.                      -n  Show the line numbers of any matches.
  17851.                      -q  Quiet:  don't show filenames where the
  17852.                          matches occur.
  17853.                      -s  Read the patterns from stdin.
  17854.                      -v  Invert the pattern:  show all lines except
  17855.                          those that match.
  17856.                      --  End of options.
  17857.  
  17858.  
  17859.             hashstat: Print Path Hashing Performance Statistics
  17860.  
  17861.                  Usage:  hashstat [-h-]
  17862.  
  17863.                     Summarize the  recent effectiveness  of the  path
  17864.                     hashing mechanism.
  17865.  
  17866.                     Hamilton C shell uses a hashing mechanism to help
  17867.                     it decide  which path  directories  and  filetype
  17868.                     extensions should tried first when looking for an
  17869.                     executable file.   This  way, it  avoids  wasting
  17870.                     time with  requests to  the OS/2 or NT kernels to
  17871.                     look for files that are known to be non-existent.
  17872.                     Sometimes, the first guess made this way is wrong
  17873.                     (the  hash  says  a  file  might  exist,  but  it
  17874.                     doesn't) and  the shell  has to  try again with a
  17875.                     different directory or extension.
  17876.  
  17877.                     hashstat shows  you the  hit rate,  which is  the
  17878.                     number of  hits divided  by the  number of  tries
  17879.                     (hits plus  misses.)   Blindspots are  files that
  17880.                     aren't found  using the  hash but  are found on a
  17881.                     second  pass,   using   an   exhaustive   search.
  17882.                     Blindspots happen  when you  add new  files to  a
  17883.                     path directory;  when detected,  they  cause  the
  17884.                     directory to be rehashed.
  17885.  
  17886.                     (See also the rehash and unhash commands.)
  17887.  
  17888.                  Options:
  17889.  
  17890.                      -h  Help.
  17891.                      --  End of options.
  17892.  
  17893.  
  17894.  
  17895.  
  17896.  
  17897.  
  17898.  
  17899.  
  17900.  
  17901.  
  17902.  
  17903.  
  17904.                                      Page 282
  17905.  
  17906.                                                                          Help
  17907.  
  17908.  
  17909.             head:     Copy the first few lines or bytes of a file to
  17910.             Stdout
  17911.  
  17912.                  Usage:  head [-hbnq<size>-] [-t<tabs>][ file1 file2
  17913.                  ... ]
  17914.  
  17915.                     head copies  the first  part of each of the files
  17916.                     you specify  onto stdout.   If  several files are
  17917.                     given, each is announced unless you specify quiet
  17918.                     mode.  You may specify how much to read from each
  17919.                     file in  either lines  or bytes.  If no files are
  17920.                     given, head reads from stdin.
  17921.  
  17922.                  Options:
  17923.  
  17924.                      -h  Help.  (This screen.)
  17925.                      -c  Count characters.  (Default is lines.)
  17926.                      -q  Quiet mode.  Don't announce the name of each
  17927.                          file as it's read.
  17928.                      -<size>    Amount to be read from each file.
  17929.                                 (Default is 10 lines or 512 bytes.)
  17930.                      -t<tabs>   Tab settings to use for viewing text.
  17931.                                 (Default is to use value given by the
  17932.                                 TABS environment variable or, if
  17933.                                 that's undefined, to do no tab
  17934.                                 expansion.)
  17935.                      -n  No tab expansion.
  17936.                      --  End of options.
  17937.  
  17938.  
  17939.             heapstat: Print Heap Usage Statistics
  17940.  
  17941.                  Usage:  heapstat [-h-]
  17942.  
  17943.                     Summarize  the  current  heap  usage,  i.e.,  the
  17944.                     number of  objects allocated  on the heap and the
  17945.                     total storage used.  Heapstats are only available
  17946.                     if they  were enabled with the -H option when the
  17947.                     shell was  started. Because  of  the  significant
  17948.                     performance penalty associated with tracking heap
  17949.                     usage, heapstats are not normally enabled.
  17950.  
  17951.                  Options:
  17952.  
  17953.                      -h  Help.
  17954.                      --  End of options.
  17955.  
  17956.  
  17957.  
  17958.  
  17959.  
  17960.  
  17961.  
  17962.  
  17963.  
  17964.  
  17965.  
  17966.                                      Page 283
  17967.  
  17968.      Help
  17969.  
  17970.  
  17971.             history:  Display the History List
  17972.  
  17973.                  Usage:  history [-srh-] [ n [m] ]
  17974.  
  17975.                     Display commands  from the  history list.   If no
  17976.                     operands are  given, show  the entire list.  If a
  17977.                     single integer `n' is specified, display the last
  17978.                     n commands.   If  both integers  `n' and  `m' are
  17979.                     given, then:
  17980.  
  17981.                        if m >= n:    Display  commands   numbered   n
  17982.                                  through m.
  17983.  
  17984.                        if m < n: Display  m  commands,  beginning  at
  17985.                                  command n.
  17986.  
  17987.                     (The size  of  the  list  is  controlled  by  the
  17988.                     history variable, changed using the set command.)
  17989.  
  17990.                  Options:
  17991.  
  17992.                      -s  Short form:  Leave off the command numbers.
  17993.                      -r  Reverse order:  Show the oldest first.
  17994.                      -h  Help.
  17995.                      --  End of options.
  17996.  
  17997.  
  17998.             kill:     Kill Specified Process or Thread Activity
  17999.  
  18000.                  Usage:  kill [-xh-] scheduling_id  [ scheduling_id
  18001.                  ... ]
  18002.  
  18003.                     Terminate specific  activities.   Normally,  only
  18004.                     direct child  screen groups  and processes can be
  18005.                     killed.   Only certain  threads will respond to a
  18006.                     kill;  you   cannot  inadvertently   kill  normal
  18007.                     internal housekeeping.
  18008.  
  18009.                     Scheduling_ids are  the thread, process or screen
  18010.                     group identifiers  as reported by the ps command.
  18011.                     An id  beginning with `t' indicates a thread; `p'
  18012.                     indicates  a  process;  `s'  indicates  a  screen
  18013.                     group.  (Screen groups are only on OS/2.)
  18014.  
  18015.                  Options:
  18016.  
  18017.                      -x  Kill even processes that are not direct
  18018.                          children.  (Has no effect on OS/2 screen
  18019.                          groups that are not direct children; this is
  18020.                          an OS/2 kernel restriction.)
  18021.                      -h  Help.
  18022.                      --  End of options.
  18023.  
  18024.  
  18025.  
  18026.  
  18027.  
  18028.                                      Page 284
  18029.  
  18030.                                                                          Help
  18031.  
  18032.  
  18033.             label:    Read/Write the Volume Label
  18034.  
  18035.                  Usage:  label [-h-]  [ disk: ] [ label ]
  18036.  
  18037.                     label reads  or writes the label on the specified
  18038.                     disk, given  as a  single alphabetic drive letter
  18039.                     plus a  colon.   If no  disk  is  specified,  the
  18040.                     current  disk   is  assumed.    If  no  label  is
  18041.                     specified, the  current label  name  is  printed.
  18042.                     Otherwise  label   tries  to  set  the  label  to
  18043.                     specified name.   Spacing  between the  disk: and
  18044.                     the label operands is optional.
  18045.  
  18046.                     The principal  differences between  this and  the
  18047.                     standard OS/2 or NT label command are that (1) it
  18048.                     can be  invoked directly  from the  C shell  (the
  18049.                     standard OS/2 label had a bug in its command line
  18050.                     processing that  meant it  had to be invoked only
  18051.                     via cmd.exe), and (2) it never prompts, making it
  18052.                     more suitable in scripts.
  18053.  
  18054.                  Options:
  18055.  
  18056.                      -h  Help.  (This screen.)
  18057.                      --  End of options.
  18058.  
  18059.  
  18060.  
  18061.  
  18062.  
  18063.  
  18064.  
  18065.  
  18066.  
  18067.  
  18068.  
  18069.  
  18070.  
  18071.  
  18072.  
  18073.  
  18074.  
  18075.  
  18076.  
  18077.  
  18078.  
  18079.  
  18080.  
  18081.  
  18082.  
  18083.  
  18084.  
  18085.  
  18086.  
  18087.  
  18088.  
  18089.  
  18090.                                      Page 285
  18091.  
  18092.      Help
  18093.  
  18094.  
  18095.              ls:      List Files or Directories
  18096.  
  18097.                  Usage:  ls [-+][lL!rqhx- ndtsez mU DHSARa 0-9 wME]
  18098.                  path1 [ path2 ... ]
  18099.  
  18100.                     ls lists  the  specified  files  or  directories.
  18101.                     Directory names  are highlighted;  names of files
  18102.                     or directories  with the system bit set are shown
  18103.                     in green.
  18104.  
  18105.                     File and  directory names  are normally converted
  18106.                     to lower  case for  better readability.   But  ls
  18107.                     will  look   for   an   environmental   variable,
  18108.                     MIXEDCASEDRIVES, giving  a list  of drives, e.g.,
  18109.                     f-hq, meaning  drives F: through H: and drive Q:,
  18110.                     which should be displayed in mixed case.
  18111.  
  18112.                     To customize  ls with  a default behavior of your
  18113.                     own choosing,  use  the  LSOPTIONS  environmental
  18114.                     variable.   ls will  first  process  any  options
  18115.                     specified in  LSOPTIONS before  any specified  on
  18116.                     the command line.
  18117.  
  18118.                  General Options:
  18119.  
  18120.                      -l  Long format listings of the files or
  18121.                          directories.
  18122.                      -L  Very Long format listings.  (Under OS/2 1.1,
  18123.                          used and allocated media space is always
  18124.                          reported.  Under 1.2, the size of any
  18125.                          extended attributes is shown instead of
  18126.                          media space if -E is specified.  Also, under
  18127.                          1.2, root directories do not have a
  18128.                          timestamp and are reported as midnight,
  18129.                          Jan 1, 1980)
  18130.                      -!  List just the names specified, not the
  18131.                          contents of any directories.  (Remember to
  18132.                          type this option at the end of the list so
  18133.                          the space afterward will prevent it being
  18134.                          confused as a history reference.)
  18135.                      -r  Recursively list contents of any
  18136.                          subdirectories.
  18137.                      -q  Quiet.  Don't generate an error message for
  18138.                          non-existent files.
  18139.                      -h  Help (short list.)
  18140.                      -hx Extended help (this description.)
  18141.                      --  End of options.  (Useful if filenames start
  18142.                          with ``-''.)
  18143.                      
  18144.  
  18145.  
  18146.  
  18147.  
  18148.  
  18149.  
  18150.  
  18151.  
  18152.                                      Page 286
  18153.  
  18154.                                                                          Help
  18155.  
  18156.  
  18157.                  Sorting Options:
  18158.  
  18159.                     Sorts may  be done in any order; default is -nds.
  18160.                     (The filename is the most important sort criteria
  18161.                     and ties are broken by date or size.)
  18162.  
  18163.                      -n  Name (lowest alphabetic first.)
  18164.                      -d  Date (oldest first.)
  18165.                      -t  Time (newest first; same as -dz)
  18166.                      -s  Size (largest first.)
  18167.                      -e  Extension (lowest alphabetic first.)
  18168.                      -z  Reverse the major or last specified sort.
  18169.                      -m  Merge the listings of directories and files.
  18170.                      -U  Unordered (in order of appearance in the
  18171.                          directory.)
  18172.                      
  18173.                  Selection Criteria:
  18174.  
  18175.                      +<type> Include files/directories fitting this
  18176.                              pattern.
  18177.                      -<type> Leave out anything fitting this pattern.
  18178.                  
  18179.                     where  <type>   is   combination   of   following
  18180.                     characters:
  18181.  
  18182.                      D   Directories.
  18183.                      H   Hidden files or directories.
  18184.                      S   System files or directories.
  18185.                      A   Archive bit set.
  18186.                      R   Read-only files or directories.
  18187.                      .   ``.'' and ``..'' files.
  18188.                      a   All files or directories regardless of
  18189.                          attributes.
  18190.                  
  18191.                     The  default   is  ``+a  -.  -H'',  meaning  list
  18192.                     anything other  than ``.''  and ``..'' not marked
  18193.                     Hidden.       Anything   specified    is    added
  18194.                     to/subtracted  from   this  set.     Ordering  of
  18195.                     additions or subtractions does make a difference.
  18196.                     If  the   slash,  ``/'',  is  used  to  introduce
  18197.                     options, it  is treated  as a plus when used with
  18198.                     selection criteria.
  18199.  
  18200.                     Selection  criteria   normally  applies  only  to
  18201.                     directories  and   files  found   by  listing   a
  18202.                     directory.   All names  given on the command line
  18203.                     will  be  listed  if  they  exist  regardless  of
  18204.                     whether they  match the selection criteria unless
  18205.                     the -c option is specified.
  18206.  
  18207.                      -c  Command line names must match criteria also,
  18208.                          unless only one name is given.
  18209.  
  18210.  
  18211.  
  18212.  
  18213.  
  18214.                                      Page 287
  18215.  
  18216.      Help
  18217.  
  18218.  
  18219.                  Listing Options:
  18220.  
  18221.                      -<integer> Specified number of columns.
  18222.                      -0  Standard multi-columns on an 80-column
  18223.                          screen.
  18224.                      -C  Capitalization.  Display filenames in the
  18225.                          upper- or lower-case characters actually
  18226.                          stored in the file system.
  18227.                      -w  Walk subdirectories to show true sizes in
  18228.                          long format listings.
  18229.                      -M  Media allocation is shown instead of amount
  18230.                          used with -l.
  18231.                      -E  Extended attribute size is shown instead of
  18232.                          media allocation with -L.  (-E is ignored
  18233.                          under OS/2 1.1.)
  18234.                      
  18235.                  Colors:
  18236.  
  18237.                     You may  set your  own choices  for screen colors
  18238.                     using these environmental variables:
  18239.  
  18240.                     Name          Use                    Default
  18241.  
  18242.                     COLORS        Normal screen colors   White on
  18243.                     Black
  18244.                     DIRECTORIES   Directories            Bright
  18245.                     SYSTEMFILES   Files with system bit set   Green
  18246.                     SYSTEMDIRS    Directories with system     (see
  18247.                     below)
  18248.                                   bit set
  18249.  
  18250.                     Colors recognized  are black, red, green, yellow,
  18251.                     blue, magenta (or red blue), cyan (or blue green)
  18252.                     or white.   Foreground  colors may also be bright
  18253.                     or blink.   The names of the colors and the words
  18254.                     bright, blink  and on  may be  in either upper or
  18255.                     lower  or   mixed  case  but  the  names  of  the
  18256.                     environmental variables  themselves must  be  all
  18257.                     upper case.
  18258.  
  18259.                     Either or  both  the  foreground  and  background
  18260.                     colors may  be specified;  if you don't specify a
  18261.                     value, it's  considered transparent  and inherits
  18262.                     the color underneath it.
  18263.  
  18264.                     SYSTEMDIRS normally inherits a merging of the
  18265.                     DIRECTORIES and SYSTEMFILES colors. DIRECTORIES
  18266.                     and SYSTEMFILES inherit from COLORS.
  18267.  
  18268.  
  18269.  
  18270.  
  18271.  
  18272.  
  18273.  
  18274.  
  18275.  
  18276.                                      Page 288
  18277.  
  18278.                                                                          Help
  18279.  
  18280.  
  18281.             markexe:  Mark the application type bits in an .exe file
  18282.  
  18283.                  Usage:  markexe [-ftpzslh-] file1 [ file2 ... ]
  18284.  
  18285.                     markexe reports or sets the application type bits
  18286.                     on  OS/2   .exe  files   to  indicate   how   the
  18287.                     application should be started, i.e., whether they
  18288.                     must run full-screen, can run in a text window or
  18289.                     must be started as full PM graphics applications.
  18290.  
  18291.                     If the  .exe is a 16-bit application, markexe can
  18292.                     also be used to indicate whether it supports long
  18293.                     filenames.   (All 32-bit  applications  must,  by
  18294.                     definition, support long filenames.)
  18295.  
  18296.                     If no flags are specified, the types are reported
  18297.                     but not altered.
  18298.  
  18299.                  Application Types:
  18300.  
  18301.                      -f  Full-screen.
  18302.                      -t  Text windowable.
  18303.                      -p  PM graphics.
  18304.                      -z  Zero the type bits.  (Undefined type.)
  18305.                      
  18306.                  Long Filename Support (ignored for 32-bit .exe
  18307.                  files):
  18308.  
  18309.                      -s  Short filenames only.
  18310.                      -l  Long (HPFS-style) filenames supported.
  18311.                      
  18312.                  Other Options:
  18313.  
  18314.                      -h  Help.  (This screen.)
  18315.                      --  End of options.
  18316.  
  18317.  
  18318.             mkdir:    Make Directories
  18319.  
  18320.                  Usage:  mkdir [-h-] directory1 [ directory2 ... ]
  18321.  
  18322.                  Options:
  18323.  
  18324.                      -h  Help.
  18325.                      --  End of options.
  18326.  
  18327.  
  18328.  
  18329.  
  18330.  
  18331.  
  18332.  
  18333.  
  18334.  
  18335.  
  18336.  
  18337.  
  18338.                                      Page 289
  18339.  
  18340.      Help
  18341.  
  18342.  
  18343.             more:     A Better More Filter
  18344.  
  18345.                  Usage:  more [-#IinNcvbodxCh-] [-rradix] [-ttabs]
  18346.                  [-sscroll]
  18347.                            [file1 file2 ... ]
  18348.  
  18349.                     This more  provides a  number of  advantages over
  18350.                     the standard  more.com filter.  It's faster, goes
  18351.                     backwards and forwards through a file, can search
  18352.                     for character  strings and  display  binary  data
  18353.                     embedded in  the text.   As  it reads  a file, it
  18354.                     builds an  ISAM structure on-the-fly that lets it
  18355.                     jump   to   a   specific   line   number   almost
  18356.                     instantaneously.   It's designed  for  very  fast
  18357.                     browsing.
  18358.  
  18359.                     On-line help  is available to the key bindings by
  18360.                     pressing ``h''  when you see the Press H for Help
  18361.                     prompt at the bottom of a screenful of data.
  18362.  
  18363.                     For  OS/2,   there  are  two  versions  of  more:
  18364.                     more.exe is  built in  small model  and can cache
  18365.                     about  11K   characters;  a   ``huge''   version,
  18366.                     moreh.exe, is  built in  large  model  and  while
  18367.                     slightly slower,  can cache  about 4M characters.
  18368.                     Where speed  is less important than being able to
  18369.                     scroll all the way back through a large amount of
  18370.                     text coming  through a pipe, use moreh.exe, which
  18371.                     was compiled in large model.
  18372.  
  18373.                  Options:
  18374.  
  18375.                      -#  Show line numbers.
  18376.                      -I  Start up in case-independent search mode.
  18377.                      -i  Go into Interactive mode immediately, which
  18378.                          means clear the screen first for faster
  18379.                          painting and put up the Press H for Help
  18380.                          prompt rather than just exiting if there's
  18381.                          less than a screenful of input.
  18382.                      -n  Next file option.  Pressing space bar when
  18383.                          the end-of-file message is displayed causes
  18384.                          more to continue with the next file or to
  18385.                          exit if there are no more files.
  18386.                      -N  No stretch.  Don't stretch color changes out
  18387.                          to the right edge of the screen.
  18388.                      -c  Show non-printables in C language style.
  18389.                      -v  Make non-printables Visible as control
  18390.                          characters.
  18391.                      -b  Show Binary values of non-printable
  18392.                          characters.
  18393.                      -o  Use Octal for binary data.
  18394.                      -d  Use Decimal for binary data.
  18395.                      -x  Use Hexadecimal for binary data.
  18396.  
  18397.  
  18398.  
  18399.  
  18400.                                      Page 290
  18401.  
  18402.                                                                          Help
  18403.  
  18404.  
  18405.                      -C  Don't clear the screen before each new
  18406.                          screenful.
  18407.                      -rradix    Use user-specified radix for binary
  18408.                          data.
  18409.                      -ttabs     Set tabs every integer number of
  18410.                          spaces.
  18411.                      -sscroll   Set the integer default scroll
  18412.                          amount.
  18413.                      --  End of options.  (Useful if a filename
  18414.                          begins with ``-''.)
  18415.                  
  18416.                     Initial tab  settings and  radix values are taken
  18417.                     from the  environmental TABS  and RADIX variables
  18418.                     if they're  defined.   Otherwise, TABS  =  8  and
  18419.                     RADIX = 16 is assumed.
  18420.  
  18421.                  Colors:
  18422.  
  18423.                     You may  set your  own choices  for screen colors
  18424.                     using these environmental variables:
  18425.  
  18426.                     Name          Use                    Default
  18427.  
  18428.                     COLORS        Normal screen colors   White on
  18429.                     Black
  18430.                     MOREEOF       End or Top of File messages Green
  18431.                     MORETOPMEM    Top of Memory message  Bright
  18432.                     Yellow
  18433.                     MOREPROMPT    Prompt line at the bottom   Green
  18434.                     MOREFILLIN    Characters typed at the     White
  18435.                                   prompt
  18436.                     MOREERROR     Unrecognizable command Bright
  18437.                     Yellow
  18438.                                   errors
  18439.  
  18440.                     Colors recognized  are black, red, green, yellow,
  18441.                     blue, magenta (or red blue), cyan (or blue green)
  18442.                     or white.   Foreground  colors may also be bright
  18443.                     or blink.   The names of the colors and the words
  18444.                     bright, blink  and on  may be  in either upper or
  18445.                     lower  or   mixed  case  but  the  names  of  the
  18446.                     environmental variables  themselves must  be  all
  18447.                     upper case.
  18448.  
  18449.                     Either or  both  the  foreground  and  background
  18450.                     colors may  be specified;  if you don't specify a
  18451.                     value, it's  considered transparent  and inherits
  18452.                     the  color   underneath  it.       MOREERROR  and
  18453.                     MOREFILLIN inherit  from MOREPROMPT.  MOREPROMPT,
  18454.                     MORETOPMEM and MOREEOF inherit from COLORS.
  18455.  
  18456.  
  18457.  
  18458.  
  18459.  
  18460.  
  18461.  
  18462.                                      Page 291
  18463.  
  18464.      Help
  18465.  
  18466.  
  18467.             mt:       Manipulate the Tape Device  (Windows NT only)
  18468.  
  18469.                  Usage:  mt [-hv-] [-f device] command1 [ command2
  18470.                  ... ]
  18471.  
  18472.                     mt is  used to  give commands to the tape device.
  18473.                     If  a   device  is   not  specified,  the  device
  18474.                     specified by  the TAPE  environment  variable  is
  18475.                     used.  If TAPE is not defined, \\.\tape0 is used.
  18476.                     By default, each command is performed once.  Many
  18477.                     operations may  be performed  multiple  times  by
  18478.                     specifying a count.
  18479.  
  18480.                     These are  the available  commands.  Only as many
  18481.                     characters as are required to uniquely identify a
  18482.                     command need  be  given.    If  no  commands  are
  18483.                     specified, status is given.
  18484.  
  18485.                        fss [n]        Forward space n setmarks.
  18486.                        fsqs [n]       Forward space to n sequential
  18487.                                       setmarks.
  18488.                        fsf [n]        Forward space n filemarks.
  18489.                        fsqf [n]       Forward space to n sequential
  18490.                                       filemarks.
  18491.                        fsr [n]        Forward space n records.
  18492.  
  18493.                        bss [n]        Back space n setmarks.
  18494.                        bsqs [n]       Back space to n sequential
  18495.                                       setmarks.
  18496.                        bsf [n]        Back space n filemark.
  18497.                        bsqf [n]       Back space to n sequential
  18498.                                       filemarks.
  18499.                        bsr [n]        Back space n records.
  18500.  
  18501.                        stp [n [p]]    Set tape position to block n in
  18502.                                       partition p.  Default is block
  18503.                                       1 in current partition.
  18504.                        stpa [n]       Set tape position absolute.  Go
  18505.                                       to block n counting from the
  18506.                                       beginning of the tape.
  18507.  
  18508.                        eod [p]        Goto to end of data in
  18509.                                       partition p.
  18510.                        weod           Write end of data at current
  18511.                                       position.
  18512.  
  18513.                        wfm [n]        Write n filemarks.
  18514.                        wsfm [n]       Write n short filemarks.
  18515.                        wlfm [n]       Write n long filemarks.
  18516.                        wsm [n]        Write n setmarks.
  18517.  
  18518.                        rewind         Rewind the tape.
  18519.                        load           Load the tape and move to the
  18520.                                       beginning.
  18521.  
  18522.  
  18523.  
  18524.                                      Page 292
  18525.  
  18526.                                                                          Help
  18527.  
  18528.  
  18529.                        lock           Lock the tape ejection
  18530.                                       mechanism.
  18531.                        tension        Adjust tension by moving to the
  18532.                                       end of tape and then rewinding.
  18533.                        unload         Rewind and unload the tape.
  18534.                        unlock         Unlock the tape ejection
  18535.                                       mechanism.
  18536.  
  18537.                        blksize [n]    Set blocksize. (Default is
  18538.                                       device default.)
  18539.  
  18540.                        compress [n]   Enable (1) or disable (0)
  18541.                                       compression.
  18542.  
  18543.                        ecc [n]        Enable (1) or disable (0) ECC.
  18544.  
  18545.                        setmarks [1]   Enable (1) or disable (0)
  18546.                                       setmark reporting.
  18547.  
  18548.                        warning [1]    Set end-of-tape warning size.
  18549.  
  18550.                        padding [1]    Enable (1) or disable (0) data
  18551.                                       padding.
  18552.  
  18553.                        status         Print status information about
  18554.                                       the tape device.
  18555.  
  18556.                        erase          Erase from current position to
  18557.                                       end of partition.
  18558.  
  18559.                        create [n [size]]  Create partitions of device
  18560.                                       default number and size.
  18561.                                       Default number and size are
  18562.                                       determined by the device.
  18563.  
  18564.                  Options:
  18565.  
  18566.                      -h  Help.  (This screen.)
  18567.                      -v  Verbose.  Status command should dump out
  18568.                          complete drive and media parameters.
  18569.                          Default is to give just brief status and
  18570.                          position information.
  18571.                      -f device  Name of the tape device to open.
  18572.                      --  End of options.
  18573.  
  18574.  
  18575.  
  18576.  
  18577.  
  18578.  
  18579.  
  18580.  
  18581.  
  18582.  
  18583.  
  18584.  
  18585.  
  18586.                                      Page 293
  18587.  
  18588.      Help
  18589.  
  18590.  
  18591.             mv:       Move Files or Directories
  18592.  
  18593.                  Usage:  mv [-filmh-] source1 [ source2 ... ]
  18594.                  destination
  18595.  
  18596.                     mv is  an intelligent  file or  directory  mover.
  18597.                     It's able  to move either files or directories as
  18598.                     objects regardless  of  whether  the  source  and
  18599.                     destination are in the same directory or even the
  18600.                     same drive.
  18601.  
  18602.                     Files being  moved anywhere on the same partition
  18603.                     are simply  renamed; the  data stays where it is.
  18604.                     Moving a file to a different partition is done by
  18605.                     copying the  file and then deleting the original.
  18606.                     If you  move a  directory but  it keeps  the same
  18607.                     parent, that  also is  a simple rename.  Moving a
  18608.                     directory to  a new  parent is done by a mkdir in
  18609.                     the new  parent  and  moving  all  the  directory
  18610.                     contents using the same ``rename where possible''
  18611.                     strategy recursively.
  18612.  
  18613.                  Options:
  18614.  
  18615.                      -f  Force read-only files to be overwritten.
  18616.                      -i  Interactive:  ask before moving each object
  18617.                          on the command line.
  18618.                      -l  Logging is on:  display the name of each
  18619.                          file or directory
  18620.                      -m  Merge sub-directories of same name in source
  18621.                          and destination.
  18622.                      -h  Help.
  18623.                      --  End of options.  (Useful if filenames start
  18624.                          with ``-''.)
  18625.  
  18626.  
  18627.             newer:    Test whether file1 is newer than all the others
  18628.  
  18629.                  Usage:  newer [-h-] [ file1 file2 ... ]
  18630.  
  18631.                     Prints ``1''  if file1 is newer, otherwise prints
  18632.                     ``0''.
  18633.  
  18634.                  Options:
  18635.  
  18636.                      -h  Help.
  18637.                      --  End of options.
  18638.  
  18639.  
  18640.  
  18641.  
  18642.  
  18643.  
  18644.  
  18645.  
  18646.  
  18647.  
  18648.                                      Page 294
  18649.  
  18650.                                                                          Help
  18651.  
  18652.  
  18653.             older:    Test whether file1 is older than all the others
  18654.  
  18655.                  Usage:  older [-h-] [ file1 file2 ... ]
  18656.  
  18657.                     Prints ``1''  if file1 is older, otherwise prints
  18658.                     ``0''.
  18659.  
  18660.                  Options:
  18661.  
  18662.                      -h  Help.
  18663.                      --  End of options.
  18664.  
  18665.  
  18666.             patchlnk: Patch ``The linker bug''  (OS/2 only)
  18667.  
  18668.                  Usage:  patchlnk [-hcw-] filename
  18669.  
  18670.                     patchlnk can  be used  to patch a specific bug in
  18671.                     your linker  if you're  having  problems  linking
  18672.                     under the Hamilton C shell on OS/2. (See also the
  18673.                     discussion under ``Known Bugs'' in the readme.too
  18674.                     file sent with Hamilton C shell.)
  18675.  
  18676.                     If you're  having problems  linking long lists of
  18677.                     .obj files,  you  should  save  a  copy  of  your
  18678.                     link.exe the  way it  is, then  patch your linker
  18679.                     with this  program and  see if  the problem  goes
  18680.                     away.
  18681.  
  18682.                     Microsoft has  discovered they  had a  bug in the
  18683.                     version of  the C  library used  to  build  their
  18684.                     link.exe releases  (roughly) 5.01.21 through (and
  18685.                     possibly past)  5.03.   In the file open routine,
  18686.                     they had  an ``off  by one  error''  that  caused
  18687.                     problems  if   the  DosSetMaxFH   (maximum   file
  18688.                     handles) parameter  for the  process allowed more
  18689.                     than 20  file handles  to be open.  There's a JLE
  18690.                     (0x7e) that  should have  been a  JB (0x72).   It
  18691.                     occurs in the following byte string (in hex):
  18692.  
  18693.                       3b 06 ?? ?? 7e 0d 9a
  18694.  
  18695.                     where the  ?'s mark bytes that can change because
  18696.                     they refer  to data  locations that move from one
  18697.                     build of link.exe to the next.  
  18698.  
  18699.                     (Since the  problem is  in the  MS C library, the
  18700.                     bug could  affect any  C program  that  tries  to
  18701.                     simultaneously  open  20  or  more  handles  with
  18702.                     stdio.   So far,  MS link.exe is only application
  18703.                     known to  do this  but  there  could  be  others.
  18704.                     patchlnk should  work on  them also  and probably
  18705.                     even on your MS C library .lib files.)
  18706.  
  18707.  
  18708.  
  18709.  
  18710.                                      Page 295
  18711.  
  18712.      Help
  18713.  
  18714.  
  18715.                     patchlnk will  scan through the file, looking for
  18716.                     occurrences, which  it will report as hex offsets
  18717.                     from the start of the file you name.  You can use
  18718.                     these numbers  to go examine the file with IBM/MS
  18719.                     patch.exe  if   you  like  and  make  the  change
  18720.                     manually.
  18721.  
  18722.                     You can  also ask  patchlnk to  make the  change,
  18723.                     using the  -w (write) option.  Nothing fancy.  It
  18724.                     just changes the first occurrence and quits.  (If
  18725.                     you really  think you  want any other occurrences
  18726.                     patched, just  keep rerunning  this.) If  want to
  18727.                     look for changes already made, use -c.
  18728.  
  18729.                  Options:
  18730.  
  18731.                      -h  Help.  (This screen.)
  18732.                      -c  Look for changes already made.
  18733.                      -w  Write the first change.
  18734.                      --  End of options.
  18735.  
  18736.  
  18737.             popd:     Pop a new Current Directory and Disk off the
  18738.             Stack
  18739.  
  18740.                  Usage:  popd [-dsh-] [ n ]
  18741.  
  18742.                     Pop an  integer n directory paths from the top of
  18743.                     the stack,  making the  top one remaining the new
  18744.                     current directory and disk.  The default for n is
  18745.                     1.
  18746.  
  18747.                     (See also the cd, dirs, pushd and rotd commands.)
  18748.  
  18749.                  Options:
  18750.  
  18751.                      -d  Discard just stack entry n, counting from 0
  18752.                          at the top, popping everything below it up
  18753.                          one level
  18754.                      -s  Silent.  Don't print the resulting directory
  18755.                          stack.
  18756.                      -h  Help.
  18757.                      --  End of options.
  18758.  
  18759.  
  18760.  
  18761.  
  18762.  
  18763.  
  18764.  
  18765.  
  18766.  
  18767.  
  18768.  
  18769.  
  18770.  
  18771.  
  18772.                                      Page 296
  18773.  
  18774.                                                                          Help
  18775.  
  18776.  
  18777.             ps:       Print Process & Thread Status
  18778.  
  18779.                  Usage:  ps [-h-]
  18780.  
  18781.                     Show the  status of  all the  screen groups (OS/2
  18782.                     only), processes  and  threads  related  to  this
  18783.                     invocation of  Hamilton C shell, highlighting the
  18784.                     current thread.
  18785.  
  18786.                     Screen groups are created when a command you type
  18787.                     requires a  different style  of  window  than  is
  18788.                     currently running.  Screen ids begin with `s'.
  18789.  
  18790.                     Processes are  created when  commands  are  typed
  18791.                     that require  other executable  programs to  run.
  18792.                     Process ids begin with `p'. OS/2 and NT will only
  18793.                     provide information on direct child processes.
  18794.  
  18795.                     Threads are concurrent activities going on inside
  18796.                     Hamilton C  shell.  Some,  such  as  the  cleanup
  18797.                     activities  that   watch  for  other  threads  or
  18798.                     processes to  end always  run in  the background.
  18799.                     Others are  created when  a command requires that
  18800.                     an internal  function be  run in  the background.
  18801.                     Thread ids begin with `t'.
  18802.  
  18803.                  Options:
  18804.  
  18805.                      -h  Help.
  18806.                      --  End of options.
  18807.  
  18808.  
  18809.             pushd:    Push a new Current Directory and Disk onto the
  18810.             Stack
  18811.  
  18812.                  Usage:  pushd [-hs-] [ -c [n] ] [ directory ]
  18813.  
  18814.                     Go to  a new  current directory  and disk, saving
  18815.                     the old  values on  the directory  stack.   If no
  18816.                     operands are  given, swap the top two elements of
  18817.                     the stack.   If the path you specify is just 3 or
  18818.                     more dots,  pushd will  interpret that specially.
  18819.                     Just as  ``..'' means  go up  one level,  ``...''
  18820.                     means up  2 levels,  ``....'' means  up 3 levels,
  18821.                     etc.  If the directory isn't found, the CDPATH is
  18822.                     searched.
  18823.  
  18824.                     (See also the cd, dirs, popd and rotd commands.)
  18825.  
  18826.                  Options:
  18827.  
  18828.                      -c  Copy an item already on the stack onto the
  18829.                          top.  This form takes an optional parameter
  18830.                          n which specifies the integer item number
  18831.  
  18832.  
  18833.  
  18834.                                      Page 297
  18835.  
  18836.      Help
  18837.  
  18838.  
  18839.                          counting from 0 at the top.  Default is
  18840.                          n == 0.
  18841.                      -s  Silent.  Don't print the resulting directory
  18842.                          stack.
  18843.                      -h  Help.
  18844.                      --  End of options.
  18845.  
  18846.  
  18847.  
  18848.  
  18849.  
  18850.  
  18851.  
  18852.  
  18853.  
  18854.  
  18855.  
  18856.  
  18857.  
  18858.  
  18859.  
  18860.  
  18861.  
  18862.  
  18863.  
  18864.  
  18865.  
  18866.  
  18867.  
  18868.  
  18869.  
  18870.  
  18871.  
  18872.  
  18873.  
  18874.  
  18875.  
  18876.  
  18877.  
  18878.  
  18879.  
  18880.  
  18881.  
  18882.  
  18883.  
  18884.  
  18885.  
  18886.  
  18887.  
  18888.  
  18889.  
  18890.  
  18891.  
  18892.  
  18893.  
  18894.  
  18895.  
  18896.                                      Page 298
  18897.  
  18898.                                                                          Help
  18899.  
  18900.  
  18901.             pwd:      Print the Current Working Directories
  18902.  
  18903.                  Usage:  pwd [-ch-] [ disk1 disk2 ... ]
  18904.  
  18905.                     pwd prints a list of the current directories.  If
  18906.                     no disks are specified, pwd looks for a DRIVEMASK
  18907.                     environmental variable  that can  be used to mask
  18908.                     off just  the  drive  you  want  reported.    The
  18909.                     DRIVEMASK  is   specified  as  a  list  of  drive
  18910.                     letters; ranges  are allowed.  Otherwise, all the
  18911.                     fixed  disk  partitions  beginning  with  c:  are
  18912.                     reported.   The current  directory on the current
  18913.                     drive is highlighted.
  18914.  
  18915.                     pwd routinely  reports everything  in lower  case
  18916.                     for better readability.  But pwd will look for an
  18917.                     environmental variable, MIXEDCASEDRIVES, giving a
  18918.                     list of  drives, e.g.,  f-hq, meaning  drives  F:
  18919.                     through  H:   and  drive   Q:,  which  should  be
  18920.                     displayed in mixed case.
  18921.  
  18922.                  Options:
  18923.  
  18924.                      -a  If no disks are specified, report on all
  18925.                          disks.
  18926.                      -c  If no disks are specified, report on just
  18927.                          the current disk.
  18928.                      -h  Help.
  18929.                      --  End of options.
  18930.                      
  18931.                  Colors:
  18932.  
  18933.                     You may  set your  own choices  for screen colors
  18934.                     using these environmental variables:
  18935.  
  18936.                     Name          Use                    Default
  18937.  
  18938.                     COLORS        Normal screen colors   White on
  18939.                     Black
  18940.                     HIGHLIGHT     Current disk           Bright
  18941.  
  18942.                     Colors recognized  are black, red, green, yellow,
  18943.                     blue, magenta (or red blue), cyan (or blue green)
  18944.                     or white.   Foreground  colors may also be bright
  18945.                     or blink.   The names of the colors and the words
  18946.                     bright, blink  and on  may be  in either upper or
  18947.                     lower  or   mixed  case  but  the  names  of  the
  18948.                     environmental variables  themselves must  be  all
  18949.                     upper case.
  18950.  
  18951.                     Either or  both  the  foreground  and  background
  18952.                     colors may  be specified;  if you don't specify a
  18953.                     value, it's  considered transparent  and inherits
  18954.  
  18955.  
  18956.  
  18957.  
  18958.                                      Page 299
  18959.  
  18960.      Help
  18961.  
  18962.  
  18963.                     the color underneath it.  HIGHLIGHT inherits from
  18964.                     COLORS.
  18965.  
  18966.  
  18967.  
  18968.  
  18969.  
  18970.  
  18971.  
  18972.  
  18973.  
  18974.  
  18975.  
  18976.  
  18977.  
  18978.  
  18979.  
  18980.  
  18981.  
  18982.  
  18983.  
  18984.  
  18985.  
  18986.  
  18987.  
  18988.  
  18989.  
  18990.  
  18991.  
  18992.  
  18993.  
  18994.  
  18995.  
  18996.  
  18997.  
  18998.  
  18999.  
  19000.  
  19001.  
  19002.  
  19003.  
  19004.  
  19005.  
  19006.  
  19007.  
  19008.  
  19009.  
  19010.  
  19011.  
  19012.  
  19013.  
  19014.  
  19015.  
  19016.  
  19017.  
  19018.  
  19019.  
  19020.                                      Page 300
  19021.  
  19022.                                                                          Help
  19023.  
  19024.  
  19025.             rehash:   Reinitialize Path Hashing
  19026.  
  19027.                  Usage:  rehash [-h-]
  19028.  
  19029.                     Hamilton C  shell uses  a  hashing  mechanism  to
  19030.                     speed up  searches of  the path  directories.  If
  19031.                     you're  performing  system  administration  work,
  19032.                     moving files  in the  path directories,  the hash
  19033.                     mechanism  may  not  always  reflect  the  latest
  19034.                     changes you've  made.   The rehash command allows
  19035.                     you to  turn re-initialize the hash by re-reading
  19036.                     all the  path directories and setting nohashing =
  19037.                     0.   (The unhash  command can  be  used  to  turn
  19038.                     hashing off.)
  19039.  
  19040.                  Options:
  19041.  
  19042.                      -h  Help.
  19043.                      --  End of options.
  19044.  
  19045.  
  19046.  
  19047.  
  19048.  
  19049.  
  19050.  
  19051.  
  19052.  
  19053.  
  19054.  
  19055.  
  19056.  
  19057.  
  19058.  
  19059.  
  19060.  
  19061.  
  19062.  
  19063.  
  19064.  
  19065.  
  19066.  
  19067.  
  19068.  
  19069.  
  19070.  
  19071.  
  19072.  
  19073.  
  19074.  
  19075.  
  19076.  
  19077.  
  19078.  
  19079.  
  19080.  
  19081.  
  19082.                                      Page 301
  19083.  
  19084.      Help
  19085.  
  19086.  
  19087.             rm:       Remove Files or Directories
  19088.  
  19089.                  Usage:  rm [-rfHSxilh-] pathname1 [ pathname2 ... ]
  19090.  
  19091.                     rm can  delete both  files and  directories.   If
  19092.                     you try  to remove a file with one of the special
  19093.                     mode bits  set (see  chmod) or a directory that's
  19094.                     not empty, it'll refuse unless you use one of the
  19095.                     options to  let it  know that's  really what  you
  19096.                     mean.
  19097.  
  19098.                  Options:
  19099.  
  19100.                      -r  Recursively remove non-empty directories.
  19101.                      -f  Force read-only files or directories to be
  19102.                          removed.
  19103.                      -H  Hidden files or directories can be removed.
  19104.                      -S  System files or directories can be removed.
  19105.                      -x  All of the above.
  19106.                      -i  Interactive:  ask before removing each
  19107.                          object on the command line.
  19108.                      -l  Logging is on:  display the name of each
  19109.                          file or directory as it's removed.
  19110.                      -h  Help.
  19111.                      --  End of options.  (Useful if filenames start
  19112.                          with ``-''.)
  19113.  
  19114.  
  19115.             rmdir:    Remove Directories
  19116.  
  19117.                  Usage:  rmdir [-h-] directory1 [ directory2 ... ]
  19118.  
  19119.                     rmdir will  only remove  empty directories.  Mode
  19120.                     bits (system, hidden or read-only) are ignored.
  19121.  
  19122.                  Options:
  19123.  
  19124.                      -h  Help.
  19125.                      --  End of options.
  19126.  
  19127.  
  19128.  
  19129.  
  19130.  
  19131.  
  19132.  
  19133.  
  19134.  
  19135.  
  19136.  
  19137.  
  19138.  
  19139.  
  19140.  
  19141.  
  19142.  
  19143.  
  19144.                                      Page 302
  19145.  
  19146.                                                                          Help
  19147.  
  19148.  
  19149.             rotd:     Rotate the Directory Stack
  19150.  
  19151.                  Usage:  rotd [-hs-] [ n ]
  19152.  
  19153.                     Rotate  the   directory  stack   an   integer   n
  19154.                     positions.     Positive   values   cause   upward
  19155.                     rotation;   negative    values   cause   downward
  19156.                     rotation.   The default is upward rotation by one
  19157.                     position.)
  19158.  
  19159.                     (See also the cd, dirs, pushd and popd commands.)
  19160.  
  19161.                  Options:
  19162.  
  19163.                      -s  Silent.  Don't print the resulting directory
  19164.                          stack.
  19165.                      -h  Help.
  19166.                      --  End of options.
  19167.  
  19168.  
  19169.             sed:      Stream Editor
  19170.  
  19171.                  Usage:  sed [-hins-] [-f scriptfile ] [-e script] [
  19172.                  script ] [ file1 file2 ...]
  19173.  
  19174.                     sed is  a special  text editor for use on streams
  19175.                     of data  where it  cycles, reading  a  line  from
  19176.                     input, applying  the  editing  operations  you've
  19177.                     specified, and  writing the result to stdout. The
  19178.                     input is  read in  a single pass and each line is
  19179.                     acted on only once.
  19180.  
  19181.                     The  editing  script  can  be  specified  on  the
  19182.                     command line  or, if  it's long and complex, in a
  19183.                     file.   If you  want to  combine a  script on the
  19184.                     command line  with any other script, you must use
  19185.                     the -e  option.  The editing operations available
  19186.                     are the usual search/replace, insert/delete, etc.
  19187.                     With each  operation, you  generally can  specify
  19188.                     the lines  in the file it should affect either by
  19189.                     line number  or matching  a pattern or a range of
  19190.                     lines.
  19191.  
  19192.                  Options:
  19193.  
  19194.                      -h         Help.  (This screen.)
  19195.                      -f scriptfile   Read the script from a file.
  19196.                                 Multiple -f options are allowed and
  19197.                                 the scripts are concatenated.
  19198.                      -e script  Take the following argument word as a
  19199.                                 script.  Multiple -e options are
  19200.                                 allowed.
  19201.                      -i         Ignore character case.
  19202.  
  19203.  
  19204.  
  19205.  
  19206.                                      Page 303
  19207.  
  19208.      Help
  19209.  
  19210.  
  19211.                      -n         Don't automatically write the
  19212.                                 contents of the edit buffer to stdout
  19213.                                 at the end of each cycle.
  19214.                      -s         Read the script from stdin.  (The
  19215.                                 input stream to be edited must be in
  19216.                                 a file.)
  19217.                      --         End of options.
  19218.  
  19219.  
  19220.  
  19221.  
  19222.  
  19223.  
  19224.  
  19225.  
  19226.  
  19227.  
  19228.  
  19229.  
  19230.  
  19231.  
  19232.  
  19233.  
  19234.  
  19235.  
  19236.  
  19237.  
  19238.  
  19239.  
  19240.  
  19241.  
  19242.  
  19243.  
  19244.  
  19245.  
  19246.  
  19247.  
  19248.  
  19249.  
  19250.  
  19251.  
  19252.  
  19253.  
  19254.  
  19255.  
  19256.  
  19257.  
  19258.  
  19259.  
  19260.  
  19261.  
  19262.  
  19263.  
  19264.  
  19265.  
  19266.  
  19267.  
  19268.                                      Page 304
  19269.  
  19270.                                                                          Help
  19271.  
  19272.  
  19273.                  Scripts:
  19274.  
  19275.                     The script  is written  as a  series of commands,
  19276.                     each separated  from the  next by a line end or a
  19277.                     semicolon.  The format of a command is:
  19278.  
  19279.                                 [ address1 [ , address2 ] ] operation
  19280.                      
  19281.                     Spacing between fields is arbitrary:  you can use
  19282.                     spaces or tabs between fields or have none at all
  19283.                     as you prefer.  Here are the fields:
  19284.  
  19285.                      address    is a line number or regular
  19286.                                 expression to be matched.  When a
  19287.                                 regular expression is used as an
  19288.                                 address, it's normally written as
  19289.                                 /regexp/ but it's also possible to
  19290.                                 use the syntax \?regexp? where ? is
  19291.                                 any character.
  19292.                      
  19293.                          Zero- or One-Address Operations:
  19294.                      
  19295.                                 If you don't give an address, the
  19296.                                 operation is applied to all lines.
  19297.                      
  19298.                                 If you give a single address, the
  19299.                                 operation is done on each line that
  19300.                                 matches.
  19301.                      
  19302.                          Ranges:
  19303.                      
  19304.                                 When you give two addresses, you
  19305.                                 define a range. A range can be a
  19306.                                 single line, e.g., ``3,3'', or a
  19307.                                 whole group of lines.  If the
  19308.                                 addresses involve pattern matching,
  19309.                                 e.g., ``/^#ifdef/,/^#endif/'', the
  19310.                                 range might occur over and over in
  19311.                                 the input and will be acted on each
  19312.                                 time.
  19313.                      
  19314.                                 Most operations, e.g.,
  19315.                                 search/replace, are done against all
  19316.                                 lines in the range.  The exceptions
  19317.                                 are i\ (insert), which is acted on at
  19318.                                 entry to the range; a\ (append), and
  19319.                                 q (quit), which are acted on at the
  19320.                                 end; and c\ (change), which deletes
  19321.                                 all the lines in the range but
  19322.                                 doesn't write any output until the
  19323.                                 end of the range.
  19324.                      
  19325.  
  19326.  
  19327.  
  19328.  
  19329.  
  19330.                                      Page 305
  19331.  
  19332.      Help
  19333.  
  19334.  
  19335.                      operation  is one of the 28 basic operations
  19336.                                 provided, together with any arguments
  19337.                                 it takes.
  19338.  
  19339.  
  19340.  
  19341.  
  19342.  
  19343.  
  19344.  
  19345.  
  19346.  
  19347.  
  19348.  
  19349.  
  19350.  
  19351.  
  19352.  
  19353.  
  19354.  
  19355.  
  19356.  
  19357.  
  19358.  
  19359.  
  19360.  
  19361.  
  19362.  
  19363.  
  19364.  
  19365.  
  19366.  
  19367.  
  19368.  
  19369.  
  19370.  
  19371.  
  19372.  
  19373.  
  19374.  
  19375.  
  19376.  
  19377.  
  19378.  
  19379.  
  19380.  
  19381.  
  19382.  
  19383.  
  19384.  
  19385.  
  19386.  
  19387.  
  19388.  
  19389.  
  19390.  
  19391.  
  19392.                                      Page 306
  19393.  
  19394.                                                                          Help
  19395.  
  19396.  
  19397.                  Operations:
  19398.  
  19399.                     There are two buffers in sed: the edit buffer and
  19400.                     the hold  buffer.  Most of the editing operations
  19401.                     work on  the edit  buffer,  doing  search/replace
  19402.                     operations, translating characters, and saving or
  19403.                     retrieving  text   in  the   hold  buffer.    sed
  19404.                     automatically puts  each new  line into  the edit
  19405.                     buffer (along  with its trailing line end) at the
  19406.                     start of  each cycle  unless there  was something
  19407.                     left over after a D (delete head) command.
  19408.  
  19409.                     A second  group of  operations  provide  ways  of
  19410.                     inserting blocks of static text.
  19411.  
  19412.                     The next  group of operations provide rudimentary
  19413.                     ways of  condition-testing and  branching and  of
  19414.                     nesting a series of operations together.
  19415.  
  19416.                     Finally there  operations for  printing and doing
  19417.                     other i/o and   for other miscellaneous things.
  19418.  
  19419.                  Basic Editing:
  19420.  
  19421.                      d          Delete this section.  Start the next
  19422.                                 cycle.
  19423.                      D          Delete from the beginning of edit
  19424.                                 buffer through and including the
  19425.                                 first line ending.  If there's text
  19426.                                 remaining, immediately start over at
  19427.                                 the top of the script without reading
  19428.                                 a new line.
  19429.                      s/.../.../[ngpw]     Search/replace using
  19430.                                 regular expressions. In the replace
  19431.                                 string, ``&'' means whatever the
  19432.                                 search string matched. ``\n'', where
  19433.                                 n is a number, means whatever matched
  19434.                                 that tagged expression in the search
  19435.                                 string.  The search and replace
  19436.                                 strings are shown here delimited with
  19437.                                 /, but you may choose any character
  19438.                                 you like that doesn't occur in either
  19439.                                 string.  The following modifiers are
  19440.                                 accepted:
  19441.                                 n      A decimal number from 1 to
  19442.                                        65,535. Substitute for just
  19443.                                        the n'th occurrence of the
  19444.                                        search pattern.
  19445.                                 g      Global.  Substitute all
  19446.                                        occurrences.
  19447.                                 p      Print the edit buffer if a
  19448.                                        change was made.
  19449.  
  19450.  
  19451.  
  19452.  
  19453.  
  19454.                                      Page 307
  19455.  
  19456.      Help
  19457.  
  19458.  
  19459.                                 w file Write the edit buffer onto the
  19460.                                        end of the file if a change
  19461.                                        was made.
  19462.                      y/.../.../[c]   Translate all occurrences of
  19463.                                 characters in the first string to the
  19464.                                 corresponding characters in the
  19465.                                 second string.  As in the tr utility,
  19466.                                 ranges are allowed, as in
  19467.                                 ``y/a-z/A-Z/''.  The optional ``c''
  19468.                                 flag can be used to complement the
  19469.                                 input range.  Either string can
  19470.                                 contain \r and \n characters.  If the
  19471.                                 first string is longer than the
  19472.                                 second, all the extra characters are
  19473.                                 mapped to the last character in the
  19474.                                 replacement string or to a null if
  19475.                                 there was none.  If the second string
  19476.                                 is longer, the extras are ignored.
  19477.                      
  19478.                  Using the Hold Buffer:
  19479.  
  19480.                      g          Get from the hold buffer.  Replace
  19481.                                 the current contents of the edit
  19482.                                 buffer.
  19483.                      G          Get from the hold buffer and paste
  19484.                                 onto the end of the edit buffer.
  19485.                      h          Hold.  Replace the contents of the
  19486.                                 hold buffer with a copy of the edit
  19487.                                 buffer.
  19488.                      H          Append to hold.  Copy the edit buffer
  19489.                                 contents onto the end of the hold
  19490.                                 buffer.
  19491.                      x          Exchange the edit and hold buffers.
  19492.                      
  19493.                  Inserting blocks of Static Text:
  19494.  
  19495.                      a\ \r\n text    Append the text to the output at
  19496.                                 the end of the cycle if this is the
  19497.                                 last line in the range.  All but the
  19498.                                 last line of text should have a ``\''
  19499.                                 just before the \r\n sequence at the
  19500.                                 end of each line.
  19501.                      c\ \r\n text    Change this section to read as
  19502.                                 shown in the following text.  Start
  19503.                                 the next cycle.
  19504.                      i\ \r\n text    Insert.  Immediately copy the
  19505.                                 following text to stdout if this is
  19506.                                 the start of the range.
  19507.                      
  19508.                  Condition-Testing, Branching and Grouping
  19509.                  operations:
  19510.  
  19511.  
  19512.  
  19513.  
  19514.  
  19515.  
  19516.                                      Page 308
  19517.  
  19518.                                                                          Help
  19519.  
  19520.  
  19521.                      b label    Branch to the label elsewhere in the
  19522.                                 script.  (If no label is given, it's
  19523.                                 to the end of the script.)
  19524.                      q          If this is the end of the range,
  19525.                                 quit.
  19526.                      t label    Branch to the label if search/replace
  19527.                                 changes have been made since the most
  19528.                                 recent input line was read or a t
  19529.                                 operation was run.
  19530.                      : label    Label.  (No address prefix is
  19531.                                 allowed.)
  19532.                      {   }      Group a series of operations
  19533.                                 together.
  19534.                      
  19535.  
  19536.  
  19537.  
  19538.  
  19539.  
  19540.  
  19541.  
  19542.  
  19543.  
  19544.  
  19545.  
  19546.  
  19547.  
  19548.  
  19549.  
  19550.  
  19551.  
  19552.  
  19553.  
  19554.  
  19555.  
  19556.  
  19557.  
  19558.  
  19559.  
  19560.  
  19561.  
  19562.  
  19563.  
  19564.  
  19565.  
  19566.  
  19567.  
  19568.  
  19569.  
  19570.  
  19571.  
  19572.  
  19573.  
  19574.  
  19575.  
  19576.  
  19577.  
  19578.                                      Page 309
  19579.  
  19580.      Help
  19581.  
  19582.  
  19583.                  Printing:
  19584.  
  19585.                      =          Write the line number to stdout.
  19586.                      l          List the contents of the edit buffer
  19587.                                 in C language style with escape
  19588.                                 sequences for binary characters.
  19589.                      p          Print.  Write the contents of the
  19590.                                 edit buffer to stdout.
  19591.                      P          Print from the beginning of the edit
  19592.                                 buffer through and including the
  19593.                                 first line ending.
  19594.                      #n         Suppress any automatic output at the
  19595.                                 end of each cycle.
  19596.                      
  19597.                  Other I/O operations:
  19598.  
  19599.                      n          Next line.  Write the contents of the
  19600.                                 edit buffer to stdout, dump any
  19601.                                 appended text and read a new line
  19602.                                 from stdin to the edit buffer.
  19603.                      N          Read the next line onto the end of
  19604.                                 the edit buffer with a \r\n sequence
  19605.                                 in between.
  19606.                      r file     Copy the contents of this file to
  19607.                                 stdout at the end of the cycle.
  19608.                      w file     Write the edit butter onto the end of
  19609.                                 the file, creating it if it doesn't
  19610.                                 exist.
  19611.                      
  19612.                  Miscellaneous:
  19613.  
  19614.                      ! operation     Don't apply this function unless
  19615.                                 the addressing doesn't match.  Invert
  19616.                                 the line selections.
  19617.                      ;          Null statement.
  19618.                      # comment  Comments and blank lines are ignored.
  19619.                      
  19620.                     If  multiple   a\  (append)   or  r  (read  file)
  19621.                     instructions are  executed (or  the same  one  is
  19622.                     iterated in  a loop),  a new entry is made on the
  19623.                     end of  a list of all the appended text blocks to
  19624.                     be copied  to stdout  at the  end of  the  cycle.
  19625.                     When the end of the cycle is finally reached, the
  19626.                     whole list is dumped, in order from the top.
  19627.  
  19628.  
  19629.  
  19630.  
  19631.  
  19632.  
  19633.  
  19634.  
  19635.  
  19636.  
  19637.  
  19638.  
  19639.  
  19640.                                      Page 310
  19641.  
  19642.                                                                          Help
  19643.  
  19644.  
  19645.                  Regular Expressions:
  19646.  
  19647.                     Search  patterns   are   specified   as   regular
  19648.                     expressions like  those used  by grep.    Regular
  19649.                     expressions are  written  in  this  notation,  in
  19650.                     decreasing precedence:
  19651.  
  19652.                      c          Any ordinary character matches
  19653.                                 itself.
  19654.                      \c         Match the literal character c.
  19655.                      ^          Beginning of line.
  19656.                      $          End of line.
  19657.                      .          Match any single character.
  19658.                      [...]      Match any single character in the
  19659.                                 list.
  19660.                      [^...]     Match any single character not in the
  19661.                                 list.
  19662.                      \n         Match whatever literal text the n'th
  19663.                                 tagged \(...\) expression matched.
  19664.                      r*         Match zero or more occurrences of r.
  19665.                      r1r2       Match expression r1 followed by r2.
  19666.                      \(r\)      Tagged regular expression.  Match the
  19667.                                 pattern inside the \(...\), and
  19668.                                 remember the literal text that
  19669.                                 matched.
  19670.                      
  19671.                     A regular expression pattern cannot contain Nulls
  19672.                     but it  can  contain  NewLine  or  CarriageReturn
  19673.                     characters (which  may be  useful with the N or G
  19674.                     commands.)
  19675.  
  19676.                     When typing  a regular  expression on the command
  19677.                     line, remember  that $,  [, ],  ^, (  and )  have
  19678.                     special meaning  to Hamilton  C shell. Put single
  19679.                     quotes around the string to turn off that special
  19680.                     meaning.   Also, even  inside quotes,  type ^^ to
  19681.                     mean ^ except when it immediately follows [.
  19682.  
  19683.                     Also, / at the beginning of a word on the command
  19684.                     line is  taken as  introducing an option.  If you
  19685.                     mean it  to be  the start  of a  script, use  the
  19686.                     ``--'' option ahead of it.
  19687.  
  19688.  
  19689.  
  19690.  
  19691.  
  19692.  
  19693.  
  19694.  
  19695.  
  19696.  
  19697.  
  19698.  
  19699.  
  19700.  
  19701.  
  19702.                                      Page 311
  19703.  
  19704.      Help
  19705.  
  19706.  
  19707.             setrows:  Set/Report the number of rows in an OS/2 window
  19708.  
  19709.                  Usage:  setrows [-h-] [ rows ]
  19710.  
  19711.                     setrows will  try to  set the  vertical height of
  19712.                     the current  window to  the specified  number  of
  19713.                     rows.  In a PM text window, almost any reasonable
  19714.                     number of  rows can  be chosen,  but full-screen,
  19715.                     you can  choose only  from this set:  12, 14, 21,
  19716.                     23, 24,  25, 27 to 30, 33, 34, 39 to 43, 45 to 50
  19717.                     and 54 to 60.  (Your hardware may not support all
  19718.                     these possibilities.)
  19719.  
  19720.                     If the  number of  rows is not specified, setrows
  19721.                     just reports the current value.
  19722.  
  19723.                     (setrows is supported only on OS/2.)
  19724.  
  19725.                  Options:
  19726.  
  19727.                      -h  Help.  (This screen.)
  19728.                      --  End of options.
  19729.  
  19730.  
  19731.             sleep:    Sleep for a Specified Period
  19732.  
  19733.                  Usage:  sleep [-hm-] [ seconds ]
  19734.  
  19735.                     Sleep the  specified integer  number  of  seconds
  19736.                     (rounded to  the next  clock tick.)  Default is 1
  19737.                     second or until an interrupt occurs.
  19738.  
  19739.                  Options:
  19740.  
  19741.                      -m  Sleep interval is in milliseconds rather
  19742.                          than seconds.
  19743.                      -h  Help.
  19744.                      --  End of options.
  19745.  
  19746.  
  19747.  
  19748.  
  19749.  
  19750.  
  19751.  
  19752.  
  19753.  
  19754.  
  19755.  
  19756.  
  19757.  
  19758.  
  19759.  
  19760.  
  19761.  
  19762.  
  19763.  
  19764.                                      Page 312
  19765.  
  19766.                                                                          Help
  19767.  
  19768.  
  19769.             source:   Read Commands from a File
  19770.  
  19771.                  Usage:  source [-nh-]  filename
  19772.  
  19773.                     Commands are  executed just as if they were typed
  19774.                     directly in  to this  thread of  Hamilton C shell
  19775.                     and  can   change  local  variables  and  current
  19776.                     directory settings.
  19777.  
  19778.                     (This differs  from typing  the name of a C shell
  19779.                     script file  as a  command; if  you  do  that,  a
  19780.                     separate thread is created.)
  19781.  
  19782.                  Options:
  19783.  
  19784.                      -n  No Execute (Just load the history list.)
  19785.                      -h  Help.
  19786.                      --  End of options.
  19787.  
  19788.  
  19789.             split:    Split a Large File into Chunks
  19790.  
  19791.                  Usage:  split [-bhs<size>-] [ infile [prefix] ]
  19792.  
  19793.                     split breaks up a large file into chunks, written
  19794.                     to a  series of output files formed of the prefix
  19795.                     plus a  .nnn extension,  where nnn  is a  3-digit
  19796.                     decimal number.   The  default prefix is 'chunk'.
  19797.                     Each chunk  will be  of the  specified number  of
  19798.                     lines or  bytes.   If only  one operand is given,
  19799.                     it's assumed  to be  the input filename unless -s
  19800.                     is specified.
  19801.  
  19802.                  Options:
  19803.  
  19804.                      -h  Help.  (This screen.)
  19805.                      -b  Count bytes.  (Default is lines.)
  19806.                      -s  Stdin is split.  (Implied if no files are
  19807.                          specified.)
  19808.                      -<size>    Chunk size.  (Defaults are 3000
  19809.                                 lines/300000 bytes.)
  19810.                      --  End of options.
  19811.  
  19812.  
  19813.  
  19814.  
  19815.  
  19816.  
  19817.  
  19818.  
  19819.  
  19820.  
  19821.  
  19822.  
  19823.  
  19824.  
  19825.  
  19826.                                      Page 313
  19827.  
  19828.      Help
  19829.  
  19830.  
  19831.             startwin: Start Win3.x Applications under OS/2 2.x
  19832.  
  19833.                  Usage:  startwin [-h-] [-s type] [ file ] [
  19834.                  arguments ]
  19835.  
  19836.                     Start  the  specified  Win3.x  application  in  a
  19837.                     Virtual DOS  machine using  the  WinStartApp  API
  19838.                     call.   This separate invisible PM application is
  19839.                     used to run the Windows application because:
  19840.  
  19841.                      (a) WinStartApp is the only way to start Win3.x
  19842.                          apps in seamless mode and
  19843.                      (b) the only way to find out when the Win3.x
  19844.                          child started by WinStartApp completes is
  19845.                          via a message queue -- and only PM
  19846.                          applications may have a message queue.
  19847.  
  19848.                     By default,  standard mode is used under OS/2 2.0
  19849.                     and enhanced  mode under  OS/2 2.1.   If seamless
  19850.                     support appears  to be  available, the default is
  19851.                     to run the application in a window using a common
  19852.                     (shared) copy  of the  Windows code; otherwise, a
  19853.                     full-screen Windows session is used by default.
  19854.  
  19855.                     If the  filename specified  to  startwin  is  not
  19856.                     fully-qualified, startwin  will search  for it in
  19857.                     the PATH  directories.  Just as with the C shell,
  19858.                     the current directory will be searched only if it
  19859.                     appears in the PATH list or if the file specified
  19860.                     is clearly a relative path (i.e., it contains a \
  19861.                     or /  or a  drive specification).   If necessary,
  19862.                     startwin will append .exe to the name specified.
  19863.  
  19864.                     startwin is  called automatically  by the C shell
  19865.                     if you type the name of a Win3.x app as a command
  19866.                     under OS/2  2.x.    The  only  reason  you  might
  19867.                     manually invoke startwin would be to override the
  19868.                     default session type.
  19869.  
  19870.                  Options:
  19871.  
  19872.                      -s type    Session type to be used, overriding
  19873.                                 the default type.  Session type
  19874.                                 numbers are as given in the OS/2
  19875.                                 pmshl.h header, including the
  19876.                                 following:
  19877.  
  19878.                          3.0 Standard Full-screen     11
  19879.                          3.0 Standard Seamless VDM    13
  19880.                          3.0 Standard Seamless Common 14 <-2.0
  19881.                          default
  19882.                          3.1 Enhanced Seamless VDM    17
  19883.                          3.1 Enhanced Seamless Common 18 <-2.1
  19884.                          default
  19885.  
  19886.  
  19887.  
  19888.                                      Page 314
  19889.  
  19890.                                                                          Help
  19891.  
  19892.  
  19893.                          3.1 Enhanced Full-screen     19
  19894.  
  19895.                      -h  Help.
  19896.                      --  End of options.
  19897.  
  19898.  
  19899.  
  19900.  
  19901.  
  19902.  
  19903.  
  19904.  
  19905.  
  19906.  
  19907.  
  19908.  
  19909.  
  19910.  
  19911.  
  19912.  
  19913.  
  19914.  
  19915.  
  19916.  
  19917.  
  19918.  
  19919.  
  19920.  
  19921.  
  19922.  
  19923.  
  19924.  
  19925.  
  19926.  
  19927.  
  19928.  
  19929.  
  19930.  
  19931.  
  19932.  
  19933.  
  19934.  
  19935.  
  19936.  
  19937.  
  19938.  
  19939.  
  19940.  
  19941.  
  19942.  
  19943.  
  19944.  
  19945.  
  19946.  
  19947.  
  19948.  
  19949.  
  19950.                                      Page 315
  19951.  
  19952.      Help
  19953.  
  19954.  
  19955.             strings:  Extract ascii strings from a file
  19956.  
  19957.                  Usage:  strings [-habetqvlodx-] [-<min>] [-r<radix>]
  19958.                  [ file1 file2 ... ]
  19959.  
  19960.                     strings will  search for any occurrences of ascii
  19961.                     text in  the files  you give it.  The presumption
  19962.                     is that  the files  are mostly binary and perhaps
  19963.                     quite large,  making it  impractical to  look  at
  19964.                     them directly.
  19965.  
  19966.                     A  string  is  normally  defined  as  4  or  more
  19967.                     printable ascii  characters terminated by a Null,
  19968.                     CarriageReturn, a  NewLine or  a  CarriageReturn-
  19969.                     NewLine  combination.     All   the  white  space
  19970.                     characters  are   considered  printable  and  are
  19971.                     included in  the length  count except  when  they
  19972.                     terminate a  string.   (To C  programmers,  these
  19973.                     printable ascii  characters are the isprint() and
  19974.                     isspace() characters.)
  19975.  
  19976.                     If  you   specify  a  series  of  files,  they're
  19977.                     searched one after the other, each one introduced
  19978.                     by name  unless you  specify Quiet  mode.    Each
  19979.                     string that's found is listed on a separate line.
  19980.                     Note that if a particular string contains NewLine
  19981.                     or  CarriageReturn   characters,   it   will   be
  19982.                     displayed as  a series  of (possibly)  very short
  19983.                     substrings, one per line.
  19984.  
  19985.                  Options:
  19986.  
  19987.                      -h  Help.  (This screen.)
  19988.                      -<min>     Minimum string length to report,
  19989.                                 specified as a decimal integer.
  19990.                      -a  Any string, even if not terminated with a
  19991.                          line ending or a null character.
  19992.                      -t  Trim leading white space from each string.
  19993.                      -b  Discard strings containing only white space.
  19994.                      -e  European characters (accented alphabetics
  19995.                          and European punctuation) will be considered
  19996.                          as ordinary printable text.
  19997.                      -n  Control characters other than Tab,
  19998.                          CarriageReturn and NewLine will be
  19999.                          considered to be string terminators just
  20000.                          like the null character.
  20001.                      -q  Quiet mode.  Don't announce the name of each
  20002.                          file as it's read.
  20003.                      -v  Verbose.  Paste the name of the file in
  20004.                          which it occurs onto the front of each
  20005.                          string.
  20006.                      -l  Long mode.  Show where each string occurs,
  20007.                          counting bytes from the beginning of the
  20008.                          file.  The radix used can be explicitly
  20009.  
  20010.  
  20011.  
  20012.                                      Page 316
  20013.  
  20014.                                                                          Help
  20015.  
  20016.  
  20017.                          chosen with -o, -d, -x, or -r; it defaults
  20018.                          to the value specified by the RADIX
  20019.                          environmental variable if defined or 16
  20020.                          otherwise.
  20021.                      -o  Octal offsets.
  20022.                      -d  Decimal offsets.
  20023.                      -x  Hex offsets shown.
  20024.                      -r<radix>  User-specified radix.
  20025.                      --  End of options.
  20026.  
  20027.  
  20028.             sum:      Checksum the contents of a file
  20029.  
  20030.                  Usage:  sum [-rxh-] [ file1 file2 ... ]
  20031.  
  20032.                     sum checksums  the contents  of each of the files
  20033.                     you specify,  writing the results to stdout along
  20034.                     with a  count of the number of 512-byte blocks it
  20035.                     read (including any partial blocks.)  If no files
  20036.                     are  given,   sum  reads  from  stdin.    sum  is
  20037.                     typically used  to validate  a file  communicated
  20038.                     over a possibly noisy communications line.
  20039.  
  20040.                     sum treats  the  characters  it  reads  as  8-bit
  20041.                     unsigned integers  and normally  just  adds  them
  20042.                     together  to   form  a  16-bit  unsigned  result.
  20043.                     Overflows are ignored.
  20044.  
  20045.                  Options:
  20046.  
  20047.                      -r  Rotated checksum.  Rotate the accumulated
  20048.                          checksum right one bit position before
  20049.                          adding each character.
  20050.                      -x  Xor'ed checksum.  For each new character, c,
  20051.                          the checksum, i, is calculated as
  20052.                          i += (i << 1) ^ c.
  20053.                      -h  Help.  (This screen.)
  20054.                      --  End of options.
  20055.                      
  20056.                     (The default  and rotated  checksums are the same
  20057.                     as those  calculated by  the UNIX  System  V  sum
  20058.                     command; the  xor  checksum  is  unique  to  this
  20059.                     implementation.)
  20060.  
  20061.  
  20062.  
  20063.  
  20064.  
  20065.  
  20066.  
  20067.  
  20068.  
  20069.  
  20070.  
  20071.  
  20072.  
  20073.  
  20074.                                      Page 317
  20075.  
  20076.      Help
  20077.  
  20078.  
  20079.             tabs:     Expand/Unexpand Tabs
  20080.  
  20081.                  Usage:  tabs [-hua-] [-<tabs>][ file1 file2 ... ]
  20082.  
  20083.                     tabs expands tab characters into spaces or, if -u
  20084.                     is specified,  unexpands spaces  into tabs  as it
  20085.                     copies the  input files  to stdout.   If no files
  20086.                     are given,  tabs reads  from stdin.   If multiple
  20087.                     files are  given, they're  concatenated one after
  20088.                     the other to stdout.
  20089.  
  20090.                     When unexpanding,  only leading  white  space  is
  20091.                     normally converted  to tabs.  If -a is specified,
  20092.                     tabs are inserted anywhere they would replace two
  20093.                     or more characters.
  20094.  
  20095.                  Options:
  20096.  
  20097.                      -h  Help.  (This screen.)
  20098.                      -u  Unexpand tabs.
  20099.                      -a  Unexpand all tabs.
  20100.                      -<tabs>    Tab settings to use for viewing text.
  20101.                                 Default is to use value given by the
  20102.                                 TABS environment variable or, if
  20103.                                 that's undefined, to assume tabstops
  20104.                                 every 8 characters.  If desired, a
  20105.                                 list of tabstops can specified,
  20106.                                 separated by commas; the difference
  20107.                                 between the last two tabs given is
  20108.                                 used a standard increment for
  20109.                                 following tabs.
  20110.                      --  End of options.
  20111.  
  20112.  
  20113.  
  20114.  
  20115.  
  20116.  
  20117.  
  20118.  
  20119.  
  20120.  
  20121.  
  20122.  
  20123.  
  20124.  
  20125.  
  20126.  
  20127.  
  20128.  
  20129.  
  20130.  
  20131.  
  20132.  
  20133.  
  20134.  
  20135.  
  20136.                                      Page 318
  20137.  
  20138.                                                                          Help
  20139.  
  20140.  
  20141.             tail:     Copy the last few lines or bytes of a file to
  20142.             Stdout
  20143.  
  20144.                  Usage:  tail [-hcfnq-] [-i<sec>] [m<msec>]
  20145.                  [-+<start>]
  20146.                            [-t<tabs>] [ file1 file2 ... ]
  20147.  
  20148.                     tail copies the last part of the file you specify
  20149.                     onto stdout.   You  may specify  where  to  begin
  20150.                     copying in  either lines  or bytes  measured from
  20151.                     either the  beginning or the end of the file.  If
  20152.                     no file  is given,  tail  reads  from  stdin.  If
  20153.                     several files are given, each is announced unless
  20154.                     you specify quiet mode.
  20155.  
  20156.                  Options:
  20157.  
  20158.                      -h  Help.  (This screen.)
  20159.                      -c  Count characters.  (Default is lines.)
  20160.                      -f  Follow.  At end of file, go into an endless
  20161.                          loop, sleeping for a second, then waking up
  20162.                          to see if more data's been added.  (Use ^C
  20163.                          to exit.)  The follow option is not valid if
  20164.                          more than one file is specified and is
  20165.                          ignored if data is being read from a pipe.
  20166.                      -i<sec>    Interval in seconds between checking
  20167.                                 for more data if -f option is used.
  20168.                                 (If the interval specified is greater
  20169.                                 than one second, tail will
  20170.                                 temporarily drop back to a one second
  20171.                                 interval anytime it finds new data
  20172.                                 when it does wake up.)
  20173.                      -m<msec>   Interval in milliseconds between
  20174.                                 checking for more data if -f option
  20175.                                 is used.
  20176.                      -<start>   Starting point, relative to the end
  20177.                                 of the file.  (Default is last 10
  20178.                                 lines or 512 bytes.)
  20179.                      +<start>   Starting point, relative to the start
  20180.                                 of the file.
  20181.                      -t<tabs>   Tab settings to use for viewing text.
  20182.                                 (Default is to use value given by the
  20183.                                 TABS environment variable or, if
  20184.                                 that's undefined, to do no tab
  20185.                                 expansion.)
  20186.                      -n  No tab expansion.
  20187.                      -q  Quiet mode.  Don't announce the name of each
  20188.                          file it's read.
  20189.                      --  End of options.
  20190.  
  20191.  
  20192.  
  20193.  
  20194.  
  20195.  
  20196.  
  20197.  
  20198.                                      Page 319
  20199.  
  20200.      Help
  20201.  
  20202.  
  20203.             tar:  Read/Write UNIX Tape Archive (tar) Format Files
  20204.  
  20205.                  Usage:  tar [-acCtMxXh FLvqs!rRfBQWZ-] [-d dir] [-m
  20206.                  map]
  20207.                            [-g hours] [-O offset] [-E endset] [-b
  20208.                  sex]
  20209.                            [ tarfile ] [ file1 file2 ... ]
  20210.  
  20211.                     tar is  used to  read or  write a  simple archive
  20212.                     format  popular   for  exchanging  files  between
  20213.                     dissimilar machines.
  20214.  
  20215.                     tar normally  expects the archive to be in a file
  20216.                     specified by  the tarfile  operand.  When listing
  20217.                     or extracting files, the following file names are
  20218.                     considered to  be in  the name space of what's in
  20219.                     the archive  and wildcards  should not  be  used.
  20220.                     When adding  files, the  names are  in the user's
  20221.                     normal file name space.
  20222.  
  20223.                     When  extracting   files,  this  version  of  tar
  20224.                     incorporates logic  to interactively  crunch up a
  20225.                     filename in  the archive  into something legal on
  20226.                     an OS/2 or NT filesystem.  If -F is specified (or
  20227.                     you're using  OS/2 1.1),  FAT  naming  rules  are
  20228.                     enforced.   Otherwise, HPFS  rules  are  assumed.
  20229.                     tar lists  these renamings  in a  .map file.  tar
  20230.                     also incorporates  logic to automatically convert
  20231.                     between the \n line ending used in an archive and
  20232.                     the \r\n  line endings  used  under  OS/2  or  NT
  20233.                     unless the file appears to be binary.
  20234.  
  20235.                  Basic Commands:
  20236.  
  20237.                      -a  Add files to the end of the archive.
  20238.                      -c  Copy the specified files in the archive to
  20239.                          stdout.
  20240.                      -C  Copy entire tar segments (including headers
  20241.                          and any padding) to stdout.  After the last
  20242.                          segment, write two blocks of zeros to mark
  20243.                          the end of a tar archive.  (If you intend to
  20244.                          concatenate archive, use the -Z option to
  20245.                          suppress writing the trailing blocks of
  20246.                          zeros.)
  20247.                      -t  List table of contents (the default).  List
  20248.                          the files in the archive.
  20249.                      -M  Just build the mapfile; don't extract
  20250.                          anything.
  20251.                      -x  Extract files from the archive.  Default is
  20252.                          all files in the archive.  (Do not use
  20253.                          wildcarding.)
  20254.                      -X  Extract everything EXCEPT the specified
  20255.                          files from the archive.
  20256.                      -h  Help.  (This screen.)
  20257.  
  20258.  
  20259.  
  20260.                                      Page 320
  20261.  
  20262.                                                                          Help
  20263.  
  20264.  
  20265.                      
  20266.  
  20267.  
  20268.  
  20269.  
  20270.  
  20271.  
  20272.  
  20273.  
  20274.  
  20275.  
  20276.  
  20277.  
  20278.  
  20279.  
  20280.  
  20281.  
  20282.  
  20283.  
  20284.  
  20285.  
  20286.  
  20287.  
  20288.  
  20289.  
  20290.  
  20291.  
  20292.  
  20293.  
  20294.  
  20295.  
  20296.  
  20297.  
  20298.  
  20299.  
  20300.  
  20301.  
  20302.  
  20303.  
  20304.  
  20305.  
  20306.  
  20307.  
  20308.  
  20309.  
  20310.  
  20311.  
  20312.  
  20313.  
  20314.  
  20315.  
  20316.  
  20317.  
  20318.  
  20319.  
  20320.  
  20321.  
  20322.                                      Page 321
  20323.  
  20324.      Help
  20325.  
  20326.  
  20327.                  Basic Options:
  20328.  
  20329.                      -F  FAT filesystem naming.  (Automatically
  20330.                          chosen if the OS/2 release level < 1.2.)
  20331.                      -L  Long listing similar to ls -L showing the
  20332.                          attributes, timestamp and length of each
  20333.                          file in the archive.
  20334.                      -v  Verbose.  Also show the offset of each file
  20335.                          from the beginning of the archive.
  20336.                      -q  Quiet.  tar normally prints the head of each
  20337.                          file as it's extracted (-x) or added (-a) to
  20338.                          the archive.  This option turns that off.
  20339.                      -s  Read the archive from stdin when listing
  20340.                          table of contents or extracting.  Write the
  20341.                          archive to stdout when adding files.
  20342.                          (Implies non-interactive.)
  20343.                      -!  Non-interactive.  Files are renamed as
  20344.                          necessary for OS/2 or NT conventions.
  20345.                          (Particularly useful with -M when trying to
  20346.                          read a new, large archive file.)
  20347.                      -r  CarriageReturn/NewLine expansion is turned
  20348.                          off. (Default is normally to convert between
  20349.                          \n in the archive and \r\n under OS/2 or NT
  20350.                          unless the file appears to be binary.)
  20351.                      -R  CarriageReturn/NewLine expansion is forced
  20352.                          ON, even for files that appear to be binary.
  20353.                      --  End of options.
  20354.                      
  20355.                  Advanced Options:
  20356.  
  20357.                      -d dir     Default destination drive and
  20358.                                 directory when extracting files.
  20359.                      -m map     Specific filename to be used for
  20360.                                 showing mappings from names in the
  20361.                                 archive to names used on OS/2 or NT.
  20362.                                 (Default is to paste a .map extension
  20363.                                 onto the name of the tar file; if -s
  20364.                                 is specified, no map file is used
  20365.                                 unless -m is given.)
  20366.                      -f         Fullpath option.  Put the full
  20367.                                 pathname (minus any disk prefix)
  20368.                                 specified on the command line into
  20369.                                 the archive header when adding.  (In
  20370.                                 this context, the full path means the
  20371.                                 full name given on the command line,
  20372.                                 not the fully-qualified name starting
  20373.                                 from the root directory.)  When
  20374.                                 extracting, use the full pathname
  20375.                                 given in the header to determine
  20376.                                 where the files will go.
  20377.                      -g hours   The number of hours GMT is ahead of
  20378.                                 the local zone, e.g., 5 hours in New
  20379.                                 York or 8 hours in California. U.S.
  20380.  
  20381.  
  20382.  
  20383.  
  20384.                                      Page 322
  20385.  
  20386.                                                                          Help
  20387.  
  20388.  
  20389.                                 daylight savings is assumed in the
  20390.                                 summer months.  (OS/2 only.)
  20391.  
  20392.  
  20393.  
  20394.  
  20395.  
  20396.  
  20397.  
  20398.  
  20399.  
  20400.  
  20401.  
  20402.  
  20403.  
  20404.  
  20405.  
  20406.  
  20407.  
  20408.  
  20409.  
  20410.  
  20411.  
  20412.  
  20413.  
  20414.  
  20415.  
  20416.  
  20417.  
  20418.  
  20419.  
  20420.  
  20421.  
  20422.  
  20423.  
  20424.  
  20425.  
  20426.  
  20427.  
  20428.  
  20429.  
  20430.  
  20431.  
  20432.  
  20433.  
  20434.  
  20435.  
  20436.  
  20437.  
  20438.  
  20439.  
  20440.  
  20441.  
  20442.  
  20443.  
  20444.  
  20445.  
  20446.                                      Page 323
  20447.  
  20448.      Help
  20449.  
  20450.  
  20451.                      -G hours   Same as -g, but without daylight
  20452.                                 savings adjustments. (Under OS/2, if
  20453.                                 neither -g nor -G is specified, tar
  20454.                                 looks for a TZ variable in the
  20455.                                 environment; if it's not defined, tar
  20456.                                 ignores the difference between local
  20457.                                 time and GMT used in the archive.
  20458.                                 Under Windows NT, the -g and -G
  20459.                                 options and the TZ variable are
  20460.                                 unnecessary since the system keeps
  20461.                                 track of the difference between local
  20462.                                 time and GMT.)
  20463.                      -O offset  Offset at which to start reading the
  20464.                                 archive file. Given in bytes from
  20465.                                 beginning of the file.
  20466.                      -E endset  Offset at which to stop reading the
  20467.                                 archive file.
  20468.                      -b sex     Byte sex in the archive:  abcd
  20469.                                 (default), badc, cdab or dcba.
  20470.                      -B         Autosense byte sex when reading.
  20471.                      -Q         Very Quiet.  tar normally warns of
  20472.                                 any garbled sections that it skipped;
  20473.                                 this turns off those warnings also.
  20474.                      -W         Warnings.  Show just the files that
  20475.                                 can't be extracted to OS/2 or NT
  20476.                                 because of their file types. (Always
  20477.                                 shown in bright red.)
  20478.                      -Z         Suppress writing the trailing blocks
  20479.                                 of zeros normally written following
  20480.                                 the last of the segments extracted
  20481.                                 with the -C option.  (Useful for
  20482.                                 concatenating segments extracted from
  20483.                                 several separate archives.)
  20484.                      
  20485.                  File Format:
  20486.  
  20487.                     Tar files  are organized  as a series of 512-byte
  20488.                     blocks. Individual  files always start on a block
  20489.                     boundary with  a header  block  followed  by  the
  20490.                     uncompressed data in the file.  At the end of the
  20491.                     file are  two blocks  filled with  binary  zeros.
  20492.                     The header has the following format:
  20493.  
  20494.                         typedef struct {
  20495.                               char  name[100],
  20496.                                     mode[8],
  20497.                                     userid[8],
  20498.                                     groupid[8],
  20499.                                     filesize[12],
  20500.                                     timestamp[12],
  20501.                                     checksum[8],
  20502.                                     linkflag,
  20503.                                     linkname[100];
  20504.  
  20505.  
  20506.  
  20507.  
  20508.                                      Page 324
  20509.  
  20510.                                                                          Help
  20511.  
  20512.  
  20513.                                     unused_chars[255];
  20514.                               } header;
  20515.  
  20516.                     Everything is  in ascii  with nulls and spaces to
  20517.                     punctuate the  fields.   Numbers  are  always  in
  20518.                     octal.   The mode,  user  and  group  ids  aren't
  20519.                     meaningful on  OS/2 and  NT and  are ignored when
  20520.                     extracting and just filled in with read/write for
  20521.                     owner, owned  by root when adding.  The timestamp
  20522.                     is in seconds since Jan 1 00:00:00 GMT 1970.  The
  20523.                     checksum is  calculated as if the field contained
  20524.                     spaces.    The  linkflag  tells  the  file  type,
  20525.                     reported in  the  long  listing  as  one  of  the
  20526.                     following:
  20527.  
  20528.                      -   Normal File
  20529.                      D   Directory
  20530.                      L   Link (not a separate file, just another name
  20531.                          for one that already exists)
  20532.                      S   Symbolic Link
  20533.                      C   Character Device
  20534.                      B   Block Device
  20535.                      F   FIFO
  20536.                      
  20537.                     Under OS/2  and NT,  only the  normal  files  and
  20538.                     directories have  any meaning.   Directories  are
  20539.                     highlighted.   The other  file types are reported
  20540.                     in bright red but otherwise ignored.
  20541.  
  20542.                  Colors:
  20543.  
  20544.                     You may  set your  own choices  for screen colors
  20545.                     using these environmental variables:
  20546.  
  20547.                     Name          Use                    Default
  20548.  
  20549.                     COLORS        Normal screen colors   White on
  20550.                     Black
  20551.                     DIRECTORIES   Directories            Bright
  20552.                     FOREIGNFILES  Filetypes not supported     Bright
  20553.                     Red
  20554.                                    by OS/2 and NT
  20555.  
  20556.                     Colors recognized  are black, red, green, yellow,
  20557.                     blue, magenta (or red blue), cyan (or blue green)
  20558.                     or white.   Foreground  colors may also be bright
  20559.                     or blink.   The names of the colors and the words
  20560.                     bright, blink  and on  may be  in either upper or
  20561.                     lower  or   mixed  case  but  the  names  of  the
  20562.                     environmental variables  themselves must  be  all
  20563.                     upper case.
  20564.  
  20565.                     Either or  both  the  foreground  and  background
  20566.                     colors may  be specified;  if you don't specify a
  20567.  
  20568.  
  20569.  
  20570.                                      Page 325
  20571.  
  20572.      Help
  20573.  
  20574.  
  20575.                     value, it's  considered transparent  and inherits
  20576.                     the  color   underneath  it.     DIRECTORIES  and
  20577.                     FOREIGNFILES inherit from COLORS.
  20578.  
  20579.  
  20580.  
  20581.  
  20582.  
  20583.  
  20584.  
  20585.  
  20586.  
  20587.  
  20588.  
  20589.  
  20590.  
  20591.  
  20592.  
  20593.  
  20594.  
  20595.  
  20596.  
  20597.  
  20598.  
  20599.  
  20600.  
  20601.  
  20602.  
  20603.  
  20604.  
  20605.  
  20606.  
  20607.  
  20608.  
  20609.  
  20610.  
  20611.  
  20612.  
  20613.  
  20614.  
  20615.  
  20616.  
  20617.  
  20618.  
  20619.  
  20620.  
  20621.  
  20622.  
  20623.  
  20624.  
  20625.  
  20626.  
  20627.  
  20628.  
  20629.  
  20630.  
  20631.  
  20632.                                      Page 326
  20633.  
  20634.                                                                          Help
  20635.  
  20636.  
  20637.             tee:      Copy Stdin to Stdout and to Each File Specified
  20638.  
  20639.                  Usage:  tee [ -a- ] file1 [ file2 ... ]
  20640.  
  20641.                     tee   is    a   ``pipe-fitting''    utility   for
  20642.                     snapshotting the  data passing through the middle
  20643.                     of a pipeline.
  20644.  
  20645.                  Options:
  20646.  
  20647.                      -a  Append to any output files that already
  20648.                          exist instead of truncating and overwriting
  20649.                          them.
  20650.                      -h  Help.
  20651.                      --  End of Options.
  20652.  
  20653.  
  20654.             touch:    Create File or Set Modification Time
  20655.  
  20656.                  Usage:  touch [-rfc-] [ mmddhhmm[yy] ] pathname1 [
  20657.                  pathname2 ... ]
  20658.  
  20659.                     touch sets the timestamp on a file to the current
  20660.                     or specified  date and time.  If the file doesn't
  20661.                     exist, the normal action is to create it.
  20662.  
  20663.                     The OS/2  1.1 kernel ignores attempts to change a
  20664.                     directory timestamp.
  20665.  
  20666.                  Options:
  20667.  
  20668.                      mmddhhmmyy      Month, Day, Hour, Minutes and
  20669.                                      Year in decimal.
  20670.                      -r  Recursively touch contents of directories.
  20671.                      -f  Force Read-only files to be touched also.
  20672.                      -c  File is Not created if it doesn't already
  20673.                          exist.
  20674.                      -h  Help.
  20675.                      --  End of options.
  20676.  
  20677.  
  20678.  
  20679.  
  20680.  
  20681.  
  20682.  
  20683.  
  20684.  
  20685.  
  20686.  
  20687.  
  20688.  
  20689.  
  20690.  
  20691.  
  20692.  
  20693.  
  20694.                                      Page 327
  20695.  
  20696.      Help
  20697.  
  20698.  
  20699.             tr:  Translate Characters Filter
  20700.  
  20701.                  Usage:  tr [-cdsnh-] [ string1 [string2] ]
  20702.  
  20703.                     tr  is   used   to   perform   simple   character
  20704.                     substitutions as  it copies  data from  stdin  to
  20705.                     stdout.   Individual characters  in  string1  are
  20706.                     mapped  to   the  corresponding   characters   of
  20707.                     string2. If string2 is too short, it is padded by
  20708.                     duplicating  its   last  character.    In  either
  20709.                     string, the  minus sign can be used to indicate a
  20710.                     range of characters.
  20711.  
  20712.                     Here's an  example which   creates  a list of all
  20713.                     the words in file1, one per line, in file2, where
  20714.                     a  word   is  taken   as  a   maximal  string  of
  20715.                     alphabetics.   (The ^n  character is  expanded by
  20716.                     the C shell into a newline character.)
  20717.  
  20718.                         % tr -csn A-Za-z ^n <file1 >file2
  20719.  
  20720.                  Options:
  20721.  
  20722.                      -h  Help.  (This screen.)
  20723.                      -c  Complement the set of characters in string1.
  20724.                      -d  Delete any occurrences of the characters in
  20725.                          string1.  (If present, string2 is ignored.)
  20726.                      -s  Squeeze all strings of repeated output
  20727.                          characters in string2 to single characters.
  20728.                      -n  Normalize line endings.  Ensure that every
  20729.                          line ends with \r\n.  Fixup any \r or \n by
  20730.                          itself or any reversed \n\r character pair.
  20731.                          When squeezing, normalization also causes
  20732.                          repeated \r\n sequences to be squeezed if
  20733.                          either \r or \n is in string2.
  20734.                      --  End of options.
  20735.  
  20736.  
  20737.  
  20738.  
  20739.  
  20740.  
  20741.  
  20742.  
  20743.  
  20744.  
  20745.  
  20746.  
  20747.  
  20748.  
  20749.  
  20750.  
  20751.  
  20752.  
  20753.  
  20754.  
  20755.  
  20756.                                      Page 328
  20757.  
  20758.                                                                          Help
  20759.  
  20760.  
  20761.             unhash:   Turn off Path Hashing
  20762.  
  20763.                  Usage:  unhash [-h-]
  20764.  
  20765.                     Normally, a  hashing  mechanism  is  used  in  an
  20766.                     attempt  to   speed  up   searches  of  the  path
  20767.                     directories.     If  you're   performing   system
  20768.                     administration work,  moving files  in  the  path
  20769.                     directories, the  hash mechanism  may not  always
  20770.                     reflect the  latest changes  you've  made.    The
  20771.                     unhash command  can be  used to turn hashing off,
  20772.                     setting nohashing = 1.
  20773.  
  20774.                     (See also the rehash and hashstat commands.)
  20775.  
  20776.                  Options:
  20777.  
  20778.                      -h  Help.
  20779.                      --  End of options.
  20780.  
  20781.  
  20782.  
  20783.  
  20784.  
  20785.  
  20786.  
  20787.  
  20788.  
  20789.  
  20790.  
  20791.  
  20792.  
  20793.  
  20794.  
  20795.  
  20796.  
  20797.  
  20798.  
  20799.  
  20800.  
  20801.  
  20802.  
  20803.  
  20804.  
  20805.  
  20806.  
  20807.  
  20808.  
  20809.  
  20810.  
  20811.  
  20812.  
  20813.  
  20814.  
  20815.  
  20816.  
  20817.  
  20818.                                      Page 329
  20819.  
  20820.      Help
  20821.  
  20822.  
  20823.             uniq:     Report unique lines in text files
  20824.  
  20825.                  Usage:  uniq [-hbcdiuw-] [ file1 file2 ...]
  20826.  
  20827.                     uniq does  a quick,  simple string  comparison of
  20828.                     adjacent  lines  in  text  files,  normally  just
  20829.                     discarding any  duplicates as it copies its input
  20830.                     to stdout.
  20831.  
  20832.                     There are  some diff-style  options for  ignoring
  20833.                     upper-/lower-case differences  or treating  white
  20834.                     spaces of  any length  as equal,  etc.  Also, you
  20835.                     can optionally choose to list only the lines that
  20836.                     occur  just   once  or   only  those   that  have
  20837.                     duplicates.
  20838.  
  20839.                     If several  files are  given, the  effect is  the
  20840.                     same as  if they  were pasted together, one right
  20841.                     after another into one long file.
  20842.  
  20843.                  Options:
  20844.  
  20845.                      -h  Help.
  20846.                      -b  Blank spaces of any length compare equal.
  20847.                          Ignore any leading or trailing white space
  20848.                          on each line.
  20849.                      -c  Preface each line with a count of the number
  20850.                          of times it occurred.
  20851.                      -d  Duplicates.  Only the lines which have at
  20852.                          least one duplicate are reported.
  20853.                      -i  Ignore character case.
  20854.                      -u  Unique lines.  Only the lines which occur
  20855.                          only once are reported.
  20856.                      -w  White space is ignored totally.
  20857.                      --  End of options.
  20858.  
  20859.  
  20860.             verify:   Turn Write Verification Mode On or Off
  20861.  
  20862.                  Usage:  verify [-h-] [ mode ]
  20863.  
  20864.                     When verification  mode is  turned on, the system
  20865.                     will always  verify that  any data  written to  a
  20866.                     disk can be read back.  The mode can be specified
  20867.                     as 0  or off,  the default,  or 1  or on.   If no
  20868.                     arguments are  given, verify  simply reports  the
  20869.                     current mode.  Under NT, verify is always on.
  20870.  
  20871.                  Options:
  20872.  
  20873.                      -h  Help.
  20874.                      --  End of options.
  20875.  
  20876.  
  20877.  
  20878.  
  20879.  
  20880.                                      Page 330
  20881.  
  20882.                                                                          Help
  20883.  
  20884.  
  20885.             vol:      List Volume Labels
  20886.  
  20887.                  Usage:  vol [-ach] [ disk1 disk2 ... ]
  20888.  
  20889.                     vol reports  the volume label information on each
  20890.                     of  the   specified  disks.    If  no  disks  are
  20891.                     specified,   vol    looks   for    a    DRIVEMASK
  20892.                     environmental variable  that can  be used to mask
  20893.                     off just  the  drive  you  want  reported.    The
  20894.                     DRIVEMASK  is   specified  as  a  list  of  drive
  20895.                     letters; ranges  are allowed.  Otherwise, all the
  20896.                     partitions beginning  with c:  are reported.  The
  20897.                     current disk's label information is highlighted.
  20898.  
  20899.                     This command  is  normally  stored  in  the  file
  20900.                     vl.exe and invoked via an alias so it can be used
  20901.                     from cmd.exe  without colliding with the internal
  20902.                     cmd.exe vol function.
  20903.  
  20904.                  Options:
  20905.  
  20906.                      -a  If no disks are specified, report on all
  20907.                          disks.
  20908.                      -c  If no disks are specified, report on just
  20909.                          the current disk.
  20910.                      -h  Help.
  20911.                      --  End of options.
  20912.                  Colors:
  20913.  
  20914.                     You may  set your  own choices  for screen colors
  20915.                     using these environmental variables:
  20916.  
  20917.                     Name          Use                    Default
  20918.  
  20919.                     COLORS        Normal screen colors   White on
  20920.                     Black
  20921.                     HIGHLIGHT     Current disk           Bright
  20922.  
  20923.                     Colors recognized  are black, red, green, yellow,
  20924.                     blue, magenta (or red blue), cyan (or blue green)
  20925.                     or white.   Foreground  colors may also be bright
  20926.                     or blink.   The names of the colors and the words
  20927.                     bright, blink  and on  may be  in either upper or
  20928.                     lower  or   mixed  case  but  the  names  of  the
  20929.                     environmental variables  themselves must  be  all
  20930.                     upper case.
  20931.  
  20932.                     Either or  both  the  foreground  and  background
  20933.                     colors may  be specified;  if you don't specify a
  20934.                     value, it's  considered transparent  and inherits
  20935.                     the color underneath it.  HIGHLIGHT inherits from
  20936.                     COLORS.
  20937.  
  20938.  
  20939.  
  20940.  
  20941.  
  20942.                                      Page 331
  20943.  
  20944.      Help
  20945.  
  20946.  
  20947.             wait:     Wait for Children to Complete
  20948.  
  20949.                  Usage:  wait [-h-]
  20950.  
  20951.                     Sleep until  a child  thread or process completes
  20952.                     or until an interrupt occurs.
  20953.  
  20954.                  Options:
  20955.  
  20956.                      -h  Help.
  20957.                      --  End of options.
  20958.  
  20959.  
  20960.             wc:       Count Words (and lines and characters)
  20961.  
  20962.                  Usage:  wc [ -lwr ] [ file1 file2 ... ]
  20963.  
  20964.                     wc prints  counts all  the  lines,  words  and/or
  20965.                     characters in  each of  the files  specified, and
  20966.                     totals for  the whole  list.   If  no  files  are
  20967.                     specified, it counts stdin.
  20968.  
  20969.                  Options:
  20970.  
  20971.                      -l  Count lines
  20972.                      -w  Count words
  20973.                      -c  Count characters
  20974.                      -h  Help.
  20975.                      --  End of options.
  20976.  
  20977.                     The default is -lwc.
  20978.  
  20979.  
  20980.             whereis:  Find where executable files are located
  20981.  
  20982.                  Usage:  whereis command
  20983.  
  20984.                     whereis is a self-loading procedure that searches
  20985.                     all the  directories on  the path,  looking for a
  20986.                     .csh, .exe,  .com, or  .cmd file corresponding to
  20987.                     the  command  specified.    All  occurrences  are
  20988.                     printed.
  20989.  
  20990.  
  20991.  
  20992.  
  20993.  
  20994.  
  20995.  
  20996.  
  20997.  
  20998.  
  20999.  
  21000.  
  21001.  
  21002.  
  21003.  
  21004.                                      Page 332
  21005.  
  21006.                                                                          Help
  21007.  
  21008.  
  21009.             xd:       Hex dump a file to Stdout
  21010.  
  21011.                  Usage:  xd [-hbwlFD Zdxor nNq-] [-r<radix>]
  21012.                            [-O <offset>] [-E <endset>]
  21013.                            [-L[<items>]] [ file1 file2 ... ]
  21014.  
  21015.                     xd dumps  its input, presumed to be in binary, in
  21016.                     variety of  formats, the  default being  hex.  If
  21017.                     more than  one file  is given,  each is dumped in
  21018.                     sequence.   If no  files are  specified, xd reads
  21019.                     from stdin.   Sequences  of lines  containing the
  21020.                     same data  are collapsed  out and  replaced by an
  21021.                     asterisk.
  21022.  
  21023.                  Options:
  21024.  
  21025.                      -h  Help.  (This screen.)
  21026.                      
  21027.                  Basic display formats:
  21028.  
  21029.                      -b  Bytes.  (Default.)
  21030.                      -w  16-bit words.
  21031.                      -l  32-bit long words.
  21032.                      -F  Short 4-byte floating point.  Floating point
  21033.                          values are always displayed in decimal.
  21034.                      -D  Double-precision 8-byte floating point.
  21035.                      -Z  Suppress leading zeros.  Normally, leading
  21036.                          zeros are shown except when displaying in
  21037.                          decimal.
  21038.                      
  21039.                  Radix to be used for offsets and data:
  21040.  
  21041.                      -d  Decimal (unsigned).
  21042.                      -x  Hex.
  21043.                      -o  Octal.
  21044.                       -r<radix> User-specified radix.  If a radix < 8
  21045.                                 is chosen, offsets are always shown
  21046.                                 in hex.
  21047.                      
  21048.                  Other options:
  21049.  
  21050.                      -O <offset>     Offset at which to begin
  21051.                                 dumping.
  21052.                      -E <endset>     Offset at which to stop dumping.
  21053.                      -L[<items>]     Number of items (bytes, words,
  21054.                                 etc.) to dump.  If -L is specified,
  21055.                                 the default is one.
  21056.                      -n  No ascii column.
  21057.                      -N  No offset column.
  21058.                      -q  Quiet mode.  Don't announce the name of each
  21059.                          file as it's read.
  21060.                      -v  Verbose.  Show lines of repeated data.
  21061.                      --  End of options.
  21062.           
  21063.  
  21064.  
  21065.  
  21066.                                      Page 333
  21067.  
  21068.      Help
  21069.  
  21070.  
  21071.             
  21072.  
  21073.  
  21074.  
  21075.  
  21076.  
  21077.  
  21078.  
  21079.  
  21080.  
  21081.  
  21082.  
  21083.  
  21084.  
  21085.  
  21086.  
  21087.  
  21088.  
  21089.  
  21090.  
  21091.  
  21092.  
  21093.  
  21094.  
  21095.  
  21096.  
  21097.  
  21098.  
  21099.  
  21100.  
  21101.  
  21102.  
  21103.  
  21104.  
  21105.  
  21106.  
  21107.  
  21108.  
  21109.  
  21110.  
  21111.  
  21112.  
  21113.  
  21114.  
  21115.  
  21116.  
  21117.  
  21118.  
  21119.  
  21120.  
  21121.  
  21122.  
  21123.  
  21124.  
  21125.  
  21126.  
  21127.  
  21128.                                      Page 334
  21129.  
  21130.                                                                            Index
  21131.  
  21132.  
  21133.  
  21134.                                        Index
  21135.  
  21136.  
  21137.             !    49, 76,  78, 144, 145,      --   76, 77, 145
  21138.                161, 168                      -=   76, 145
  21139.             !!   49, 50, 130, 151, 165       -A   76, 145, 146
  21140.             !$   151                         -D   76, 77, 145, 146
  21141.             !*   151                         -e   76, 77, 124, 145, 146
  21142.             !-1       130, 165               -f   76, 145, 146
  21143.             !-n       151                    -H   76, 145, 146
  21144.             !=   76, 79, 145                 -h option      27, 175, 178
  21145.             !?   51, 67, 151                 -L   8, 112
  21146.             !^   151                         -o   76, 145, 146
  21147.             !~   76, 79, 145, 148            -R   145, 146
  21148.             !n   151                         -S   76, 145, 146
  21149.             !str      151                    -w   76, 145, 146
  21150.             #    133, 143                    -x   76, 89, 145, 146
  21151.             #!/bin/csh     134               -z   76, 145, 146
  21152.             $    56, 68, 160, 165            ...       63, 148
  21153.             $#   153                         .cshrc    134
  21154.             $*   153                         .history       134
  21155.             $<   153                         .login    134
  21156.             $?   153                         .logout   134
  21157.             ${ }      56                     /    76, 145
  21158.             $0 .. $9       97, 153           //   76, 78, 145
  21159.             %    52, 68,  76, 78,  145,      //=       145
  21160.                151                           /=   76, 145
  21161.             %%   52, 173                     /K "%*"   112
  21162.             %=   76, 145                     :#   132, 154
  21163.             %c   173                         :$   67, 154
  21164.             %d   173                         :%   67, 154
  21165.             %e   173                         :&   154
  21166.             %f   173                         :*   67, 154
  21167.             %g   173                         :^   67, 154
  21168.             %o   173                         :b   132, 155
  21169.             %s   173                         :e   155
  21170.             %x   173                         :f   155
  21171.             &    68, 75,  76, 79,  104,      :g...     68, 154
  21172.                144, 145                      :h   68, 155
  21173.             &&   75, 80,  85, 86,  126,      :n   67, 154
  21174.                127, 144, 145                 :n*       154
  21175.             &=   76, 145                     :n-       154
  21176.             ( )       75, 76, 144, 145       :n-m      67, 154
  21177.             *    61, 76, 145, 148, 163,      :p   67, 69, 154
  21178.                165                           :q   69, 154
  21179.             **   76, 78, 131, 145            :r   155
  21180.             **=       76, 131, 145           :s/str1/str2/       68, 154
  21181.             *=   76, 145                     :t   155
  21182.             +    76, 145                     :x   69, 154
  21183.             ++   76, 77, 145                 <    75, 76,  79, 144, 145,
  21184.             +=   76, 145                        163, 165
  21185.             -    76, 145                     <<   45, 75,  76, 77,  144,
  21186.             -! option      15, 36               145
  21187.  
  21188.  
  21189.  
  21190.                                       Page 335
  21191.  
  21192.      Index
  21193.  
  21194.  
  21195.             <<=       76, 145                ||   75, 80,  85, 126, 127,
  21196.             <=   76, 79, 145                    144, 145
  21197.             <DownArrow>    25, 150           ~    61, 76, 78, 145
  21198.             <End>     25, 150                abs()     171
  21199.             <Esc>     150                    Absolute value      171
  21200.             <Fx>      142                    acos()    171
  21201.             <Home>    25, 150                ADDITIONS      12,     115,
  21202.             <Insert>       25, 150              157, 165, 195
  21203.             <LeftArrow>    25, 150           Alias statement     1,  14,
  21204.             <PageDown>     150                  15, 24,  26, 34, 65, 66,
  21205.             <PageUp>       150                  83, 84,  111, 113,  117,
  21206.             <RightArrow>   25, 150              129, 130, 133, 140, 178,
  21207.             <UpArrow>      25, 150              179, 180, 181
  21208.             =    76, 79, 145                 Alt-<DownArrow>     150
  21209.             =//       76                     Alt-<End>      150
  21210.             ==   76, 79, 145                 Alt-<Enter>    25, 151
  21211.             =~   76, 79, 145, 148            Alt-<Fx>       142
  21212.             >    41, 42,  53,  75,  76,      Alt-<Home>     150
  21213.                79, 144, 145                  Alt-<Insert>   25, 150
  21214.             >!   42, 144                     Alt-<LeftArrow>     150
  21215.             >&   43, 144                     Alt-<RightArrow>    150
  21216.             >&!       144                    Alt-<UpArrow>       150
  21217.             >=   76, 79, 145                 Alt-D     26, 149
  21218.             >>   41, 42,  75,  76,  77,      Alt-F     26, 149
  21219.                144, 145                      Alternation    61, 63,  64,
  21220.             >>!       42, 144                   79, 148
  21221.             >>&       144                    ANSI escapes   17, 29,  44,
  21222.             >>&!      144                       72, 132,  152, 172, 176,
  21223.             >>=       76, 145                   196
  21224.             ?    61, 148                     ansi()    172
  21225.             @ statement    58, 75, 140,      app       179
  21226.                163, 165                      Append to a file    144
  21227.             [ ]       75, 76, 130, 145       arc       39
  21228.             [^a-z]    148                    Archive bit    146
  21229.             [a-z]     148                    args      125
  21230.             ^    41, 52,  68,  72,  76,      argv      54, 71,  97,  98,
  21231.                79, 145, 152                     99, 123,  124, 125, 129,
  21232.             ^=   76, 145                        153, 161, 163, 165
  21233.             ^^   72, 152                     Arrays    1, 58
  21234.             ^a   72, 152                     asin()    171
  21235.             ^b   72, 152                     Assignment operators     79
  21236.             ^C   100, 101                       , 145
  21237.             ^f   72, 152                     atan()    171
  21238.             ^n   72, 152                     Attribute bits      29
  21239.             ^r   72, 152                     Audible alert       152
  21240.             ^t   72, 152                     aux port       147
  21241.             ^v   72, 152                     Background activities    55
  21242.             ^Z   38, 117                        , 103,  104,  107,  133,
  21243.             { }       145                       144, 181
  21244.             {a,b}c    148                    Background colors   116
  21245.             |    43, 75,  76, 79,  144,      Backquotes     44, 71, 152
  21246.                145                           Backspace      152
  21247.             |&   43, 144                     bad blocks     204
  21248.             |=   76, 145                     Basic statements    23, 137
  21249.  
  21250.  
  21251.  
  21252.                                       Page 336
  21253.  
  21254.                                                                            Index
  21255.  
  21256.  
  21257.             beep      179, 181               CDISK     23, 53,  54, 158,
  21258.             bell      152                       160, 161, 165, 169
  21259.             Berkeley 4.3 Buglist     12      CDPATH    113,  157,   160,
  21260.                9                                165, 166, 186, 225
  21261.             Berkeley Compatibility Mode      ceil()    171
  21262.                  129, 134                    char()    172
  21263.             Berkeley-style History   11      chcp      175, 187
  21264.                8                             chdir     117, 118, 175
  21265.             bin       11                     Checksum       239
  21266.             binedit   176, 185               chgdisk   117,  161,   166,
  21267.             Bit And   79, 145                   186
  21268.             Bit Not   78                     child     163, 166
  21269.             Bit Or    79, 145                childpath()    171
  21270.             Bit Shifting   145               chmod     31, 32,  42, 176,
  21271.             Bit Xor   79, 145                   187, 228
  21272.             bits.csh       125               Cipher Block Chaining    19
  21273.             BIX       21                        2
  21274.             black     116                    cl.csh    125
  21275.             Blindspots     132               Clear the screen    175,
  21276.             blink     116                       187
  21277.             blue      116                    clock$    147
  21278.             blue green     116               cls       175, 187
  21279.             blue red       116               cmd.exe   3, 4,  8, 14, 15,
  21280.             boot record    197,    201,         23, 24,  26, 41, 53, 56,
  21281.                204                              65, 83,  85,  112,  113,
  21282.             boot sector    203                  117, 119, 125, 133, 134,
  21283.             break statement     88,             137, 157, 166, 179, 181,
  21284.                138, 143                         183, 184, 186, 191, 213,
  21285.             breaksw   130, 179                  250
  21286.             bright    116                    Code Pages     175, 187
  21287.             bsdargv   130, 161, 165          code()    172
  21288.             bsdhistory     117,    118,      Colon operators     67, 68,
  21289.                130, 160, 165                    69, 76, 154, 155
  21290.             Bug Reports    21                COLORS    4,  12,  17,  53,
  21291.             Built-in Procedures      17         115, 157, 166, 172, 195,
  21292.                1                                205, 216, 219, 226, 245,
  21293.             Built-in Utilities       17         250
  21294.                5                             colors.csh     12, 17, 125
  21295.             bumpdate.csh   125               com1 .. com7   147
  21296.             calc statement      75,          Comma operator      76
  21297.                131, 140                      Command completion       1,
  21298.             caldate.csh    125                  25, 49,  115, 131,  151,
  21299.             calendar.csh   125                  157, 168
  21300.             Calling a Procedure      94      Command line editing     1,
  21301.             callstack tracing   184             24, 25, 131, 150
  21302.             Carriage Return     152          Command line options     17
  21303.             case statement      88,             , 28
  21304.                130, 138                      Command substitution     1,
  21305.             cat       176, 185                  26,  44,  67,  71,  115,
  21306.             cd   113, 175, 186, 196             123, 152
  21307.             cdd       179                    Comments       133, 143
  21308.             cdhome    54,   117,   161,      Common Problems     3, 13
  21309.                165, 186                      Communication ports      14
  21310.                                                 7
  21311.  
  21312.  
  21313.  
  21314.                                       Page 337
  21315.  
  21316.      Index
  21317.  
  21318.  
  21319.             Communications Manager   19      Ctrl-D    26, 149
  21320.             Compare files       176,         Ctrl-F    26, 149
  21321.                194                           Ctrl-Z    38, 117
  21322.             Comparisons of strings   79      Current directory   14, 32,
  21323.             Compatibility guide      12         33, 54,  87,  107,  111,
  21324.                9                                115, 117, 143, 157, 161,
  21325.             CompuServe     21                   165, 166, 167, 175, 186,
  21326.             COMSPEC   13, 53, 119, 157,         196, 224, 225, 226, 236
  21327.                166, 184                      Current drive       143
  21328.             con device     147               Customizing the Shell    3,
  21329.             concat()       172                  111
  21330.             Condition-testing   137          cut       37, 176, 191
  21331.             Conditional execution    85      cwd       23, 54, 115, 117,
  21332.                , 144                            161, 166
  21333.             Conditional selection    14      cyan      116
  21334.                5                             Data Encryption Standard      
  21335.             config.sys     4, 5,  6, 7,         176, 192, 193
  21336.                8,  16,  28,  111,  113,      date      176, 179, 191
  21337.                116, 119                      Daylight Savings    159,
  21338.             conin$    147                       170, 243, 244
  21339.             conout$   147                    default clause      138
  21340.             Console   147                    default command processor     
  21341.             Continuation lines       11         3, 8
  21342.                4, 169                        del       15, 65,  66,  83,
  21343.             continue statement       14         179
  21344.                3                             DELETIONS      12,     115,
  21345.             Control Panel       11, 12          157, 166, 195
  21346.             Control structures       87      deltaday.csh   125
  21347.                , 88, 129                     DES       176, 192, 193
  21348.             copy      15, 29,  65,  66,      di   179
  21349.                83, 179                       diff      12, 36, 115, 157,
  21350.             cos()     171                       165, 166, 176, 179, 194,
  21351.             cosh()    171                       195, 208, 249
  21352.             cp   29, 30, 176                 dim       116, 176, 196
  21353.             crash.csh      21                dir       23, 83, 179, 242
  21354.             CreateProcess       24, 104      DIRECTORIES    115,    157,
  21355.             cron      176, 189, 190             166, 216, 245
  21356.             crontab   189, 190               Directory stack     33, 34,
  21357.             csh.exe   5, 6, 7, 53, 112,         87, 175,  196, 224, 225,
  21358.                117, 134, 158, 169               229
  21359.             CSHOPTIONS     119,    157,      dirs      33, 87, 113, 175,
  21360.                166, 184                         186, 196, 224, 225, 229
  21361.             Ctrl key       25                Disk usage     176, 205
  21362.             Ctrl-<Backspace>    150          diskette duplication     19
  21363.             Ctrl-<DownArrow>    150             7, 198, 200, 203
  21364.             Ctrl-<End>     150               DosExecPgm     24, 104, 133
  21365.             Ctrl-<Enter>   25, 151           DosQAppType    13
  21366.             Ctrl-<Fx>      142               DosRead   46
  21367.             Ctrl-<Home>    150               DosSelectDisk       161,
  21368.             Ctrl-<Insert>       25, 150         166
  21369.             Ctrl-<LeftArrow>    150          DosSetMaxFH    223
  21370.             Ctrl-<RightArrow>   150          DosSMSetTitle       112
  21371.             Ctrl-<UpArrow>      150          DosStartSession     24, 133
  21372.             Ctrl-C    104                    DosWrite       127
  21373.  
  21374.  
  21375.  
  21376.                                       Page 338
  21377.  
  21378.                                                                            Index
  21379.  
  21380.  
  21381.             Double quotes       54, 59,      Exclusion ranges    132,
  21382.                71, 76, 152                      148
  21383.             DRIVEMASK      16, 32,  62,      Executable files    133,
  21384.                113, 114, 157, 166, 205,         146
  21385.                226, 250                      exit statement      47,
  21386.             driveno()      171                  127, 143, 162, 163, 164,
  21387.             dskread   39,   176,   197,         167, 170, 180, 183
  21388.                199, 200, 201, 203, 204       exp()     171
  21389.             dskwrite       39,     176,      Exponentiation      78
  21390.                197, 199, 200, 201, 203,      Export restrictions      19
  21391.                204                              2
  21392.             dt   179                         Expression operators     57
  21393.             du   16, 32, 113, 157, 166,         , 75, 76, 130, 145, 148
  21394.                176, 179, 205                 Expression parsing       75
  21395.             duc       179                       , 76
  21396.             dumpenv   4, 125                 Expressions    1,  26,  75,
  21397.             dumphist       179                  76, 81,  93,  125,  137,
  21398.             duplicat.csh   125                  138, 140, 145
  21399.             DUPLICATES     115,    157,      Extensions     131, 133
  21400.                166                           External Utilities       17
  21401.             easter.csh     125                  6, 177, 178
  21402.             echo      29, 175                f    179
  21403.             echoinput      162,    163,      Factor.csh     123, 125
  21404.                166                           FAX       21
  21405.             Editing   67                     fflush    127
  21406.             Electronic Code Book     19      fgrep     34, 45, 176, 179,
  21407.                2                                208
  21408.             elif      130, 138               File exists    146
  21409.             elif clause    138               File system tests   1,  75,
  21410.             ellipsis       63                   76, 77, 124, 145, 146
  21411.             else clause    137, 138          Filename completion      26
  21412.             encryption     176,    192,         , 115,  149,  151,  157,
  21413.                193                              166, 168, 184
  21414.             End of file    38                Filename functions       17
  21415.             endif     130, 179, 230             1
  21416.             endsw     130, 179               finance.csh    93, 126
  21417.             environment variables    11      Floating point arithmetic     
  21418.             Environmental variables             131, 162
  21419.                1, 13,  17, 53, 54, 111,      floor()   123, 171
  21420.                112, 113, 117, 125, 157,      fn   179
  21421.                158, 159, 165                 for statement       75, 89,
  21422.             eofgetline     163, 166             131, 139, 143
  21423.             Epsilon   19                     foreach statement   89,
  21424.             Equality test operator   79         139, 143
  21425.             erase     66, 83, 179            Foreground activities    10
  21426.             Error handling      118             3, 104
  21427.             Escape sequences    29, 44,      Foreground colors   116
  21428.                72, 132, 152, 176, 196        Foreground priority      20
  21429.             escapesym      72,     117,         7
  21430.                118, 152, 157, 160, 166,      FOREIGNFILES   115,    157,
  21431.                167, 206                         167, 245
  21432.             eval      106,  126,   175,      Form Feed      152
  21433.                179, 207                      Formatting     198
  21434.  
  21435.  
  21436.  
  21437.  
  21438.                                       Page 339
  21439.  
  21440.      Index
  21441.  
  21442.  
  21443.             Full-screen applications         History long-form   49,
  21444.                5, 6,  7, 13,  14,  103,         160, 167
  21445.                217                           History short-form       51
  21446.             fullname       113                  , 160, 167
  21447.             fullpath()     90, 155, 171      history.csh    134
  21448.             Function keys       1, 142       HOME      4,  11,  12,  14,
  21449.             g    180                            53, 111,  113, 157, 159,
  21450.             getchar   163, 167, 180             160, 167, 180
  21451.             getline   69,   163,   165,      Home directory expansion      
  21452.                166, 167                         61
  21453.             getprio.c      126               HPFS      1, 3,  113,  217,
  21454.             Global editing      68, 154         242
  21455.             GMT       159,  170,   243,      Hyperbolic functions     17
  21456.                244                              1
  21457.             goto statement      99,          I/O redirection     26, 41,
  21458.                100, 143, 161, 167               44,  54,  71,  86,  104,
  21459.             gotowindow     100,    161,         118, 130, 132, 137, 144
  21460.                167                           icon      3, 8, 112
  21461.             green     116                    Idle time      207
  21462.             grep      16, 34,  35,  36,      if statement   87, 88, 137,
  21463.                176, 180, 208, 209, 234          138, 179
  21464.             Group Main     17                ignoreeof      117,    163,
  21465.             Group menu     112                  167
  21466.             Group-Main     8                 ignoreerrors   97, 98, 117,
  21467.             Grouping statements      14         118, 162, 163, 167
  21468.                3                             ignorestatus   97, 98, 117,
  21469.             h    180                            118, 163, 167
  21470.             Hashing of path directories      Indefinite Directories   61
  21471.                  24, 113, 132, 183              , 63, 148
  21472.             hashstat       175,    210,      Initial current directories
  21473.                248                                116
  21474.             head      37,   113,   158,      Inline data    44, 45,  46,
  21475.                176, 211, 231                    49, 144
  21476.             heapstat       175,    183,      Installation   3, 8, 111
  21477.                211                           Installation on  Windows NT
  21478.             help      180                         11
  21479.             Hex dump       178               interactive    162,    163,
  21480.             Hex numbers    76                   167, 180, 183, 184
  21481.             Hidden files   27, 29,  39,      Internet       21
  21482.                93, 146, 148, 161, 168        Interrupts     37, 43,  99,
  21483.             HIGHLIGHT      115,    157,         100, 143, 162, 163, 168
  21484.                167, 205, 226, 250            irqmask   101, 163, 168
  21485.             histchars      117,    151,      isinteger()    172
  21486.                160, 167                      isnumber()     172
  21487.             History   1,  15,  25,  26,      Iteration      26, 85,  89,
  21488.                49, 50,  51, 67, 69, 71,         131, 139, 143
  21489.                78, 98,  99,  111,  117,      Julian date    125, 126
  21490.                118, 129, 130, 132, 134,      julian.csh     126
  21491.                142, 150, 151, 152, 154,      kbd$      147
  21492.                155, 160, 163, 164, 167,      kill      105, 175, 212
  21493.                169, 170, 175, 179, 180,      label command       176,
  21494.                183, 212, 214, 236               213
  21495.             History editing     69           Labels and Gotos    99,
  21496.                                                 133, 143
  21497.  
  21498.  
  21499.  
  21500.                                       Page 340
  21501.  
  21502.                                                                            Index
  21503.  
  21504.  
  21505.             LAN manager    3                 MIXEDCASEDRIVES     113,
  21506.             Language Reference       11         114, 158, 168, 214
  21507.                7, 136, 137                   mkdir     83,   176,   180,
  21508.             ld   180                            217, 222
  21509.             Less than operator       79      Mode bits      176,    187,
  21510.             Less than or equal operator         228
  21511.                  79                          Modulo division     78
  21512.             link.exe       223               more      4,  12,  13,  30,
  21513.             List files     214                  31, 37, 43, 44, 83, 111,
  21514.             ll   180                            113, 115, 116, 158, 168,
  21515.             loadhist       180                  169, 170, 176, 177, 180,
  21516.             local statement     55, 141         194, 218
  21517.             Local time     159,    170,      MOREEOF   115,  158,   168,
  21518.                243, 244                         219
  21519.             Local variables     55, 92,      MOREERROR      12,     115,
  21520.                94, 106,  117, 131, 141,         158, 168, 219
  21521.                236                           MOREFILLIN     12,     115,
  21522.             log()     171                       158, 168, 219
  21523.             log10()   171                    moreh     31, 177, 180, 218
  21524.             log2()    171                    MOREPROMPT     12,     115,
  21525.             Logical And    80, 145              158, 168, 219
  21526.             Logical Not    78                MORETOPMEM     116,    158,
  21527.             Logical Or     80, 145              168, 219
  21528.             login.csh      4, 5,  6, 7,      move      29
  21529.                11, 62,  111, 112,  113,      Move files     222
  21530.                116, 117, 125, 134, 183       mt   158, 170, 177, 220
  21531.             logout.csh     134               mv   29, 83, 177, 222
  21532.             Long filenames      1,   3,      myecho    126
  21533.                39, 217                       NETWORKBUG     16, 158, 168
  21534.             Low-level format    200,         New Line       152
  21535.                202                           newer     177, 222
  21536.             lower()   172                    newfiles.csh   126
  21537.             lpt1 .. lpt4   147               noclobber      41, 42, 117,
  21538.             ls   27,  113,   115,  157,         118, 161, 168
  21539.                158, 166, 176, 214            noglob    161, 168
  21540.             LSOPTIONS      157,    168,      nohashing      161, 168
  21541.                214                           nonohidden     93,     148,
  21542.             magenta   116                       161, 168
  21543.             Make directories    217          nonomatch      64, 65, 117,
  21544.             make.exe       15                   118, 161, 162, 169
  21545.             makecpgm.csh   126               nonovar   56, 64, 162, 169
  21546.             markexe   14, 176, 217           Not equal operator       79
  21547.             Masking Interrupts       10      nowild    65, 66, 161, 162,
  21548.                1                                168, 169, 179, 180, 181
  21549.             Match failures      64           NTVersion      160, 169
  21550.             MATCHFAIL      115,    157,      nul       147
  21551.                168                           null device    147
  21552.             Math functions      171          nullwords      58, 59,  97,
  21553.             MCI Mail       21                   117, 118, 162, 169
  21554.             mcvisa.csh     126               Numeric literals    76
  21555.             md   180                         Octal numbers       76
  21556.             mi   83, 91, 180                 older     92, 177, 179, 223
  21557.             mih       180                    on   116
  21558.             mis       180                    onintr    100, 101
  21559.  
  21560.  
  21561.  
  21562.                                       Page 341
  21563.  
  21564.      Index
  21565.  
  21566.  
  21567.             onintr statement    143          printf()       172, 173
  21568.             op= operators       80           priority       207
  21569.             Order of Evaluation      10      prn       147
  21570.                9                             Problems       3, 13
  21571.             Ordinary file       146          proc statement      14, 65,
  21572.             OS/2 1.1       3,  4,   15,         66, 91, 92, 93, 94, 106,
  21573.                17, 112, 214, 216, 242           123, 124, 131, 139
  21574.             OS/2 1.2       3,  15,  17,      Procedure arguments      92
  21575.                112, 214, 243                 Procedures     1,  23,  34,
  21576.             OS/2 1.3       8, 111, 112          55, 65,  75, 76, 83, 85,
  21577.             OS/2 2.0       18                   87, 91,  93,  115,  129,
  21578.             OS/2 2.x       111,    112,         131, 132, 133, 139, 163,
  21579.                237                              167, 170, 171, 172
  21580.             os2version     160, 169          Process-wide variables   16
  21581.             Ownership      146                  0
  21582.             Parenthesis    54, 86,  87,      processid      160,    165,
  21583.                129, 130                         169
  21584.             patchlnk       15,     177,      Product Support     21
  21585.                223, 224                      Program Manager     12
  21586.             PATH      4,  11,  12,  53,      Programming constructs   75
  21587.                54, 158, 159, 160, 169           , 85
  21588.             Pathname editing    68, 155      Prompt strings      111,
  21589.             Pattern fails operator   79         113, 114, 134
  21590.                , 148                         prompt1   23, 53, 113, 114,
  21591.             Pattern matches operator            115, 134, 158, 160, 169
  21592.                79, 148                       prompt2   45, 53, 113, 114,
  21593.             Pattern matching    1,  75,         134, 158, 160, 169
  21594.                124, 145, 148, 230            Protection attributes    42
  21595.             pause     180                    PROTSHELL      8, 19,  111,
  21596.             Per-thread variables     13         112
  21597.                3, 161, 162, 163, 164         ps   104,  105,  175,  212,
  21598.             Pipes     41, 43,  44,  86,         225
  21599.                129, 144, 162                 pushd     33, 35, 113, 175,
  21600.             pkzip     39                        186, 196, 224, 225, 229
  21601.             PM applications     13, 14,      pwd       16, 32, 113, 157,
  21602.                217                              166, 177, 226
  21603.             pmcpl     103                    q    180
  21604.             pointer$       147               Quoting   26, 69,  71,  72,
  21605.             popd      33, 34,  35, 113,         125, 132, 148, 152
  21606.                175, 186, 196, 224, 225,      RADIX     158,  169,   218,
  21607.                229                              219, 238, 239, 252
  21608.             Popular Aliases     179          Ranges    61, 63,  67,  89,
  21609.             postage.csh    126                  148, 157, 166, 226, 250
  21610.             Precedence     76, 86, 144,      Raw Sectors    197, 200
  21611.                145, 209, 234                 rcode     85, 89, 126, 127
  21612.             precision      54, 57,  58,      rd   83, 180
  21613.                162, 169                      Re-entrancy    106
  21614.             Predefined variables     15      Read-only files     146
  21615.                6, 165,  166, 167,  168,      recursion      55, 93,  94,
  21616.                169, 170                         123, 125
  21617.             Print formatting    172,         red       116
  21618.                173                           Regular expressions      34
  21619.             Print spooler       147             , 35,  36, 68, 176, 208,
  21620.             Printer ports       147             209, 231, 234
  21621.  
  21622.  
  21623.  
  21624.                                       Page 342
  21625.  
  21626.                                                                            Index
  21627.  
  21628.  
  21629.             rehash    14,   132,   175,      set statement       54, 55,
  21630.                210, 227, 248                    129, 140, 141
  21631.             Relation-testing    145          Set variables       54
  21632.             Removable drives    16           setenv statement    4,   5,
  21633.             remove    29, 30                    53, 54,  55,  111,  116,
  21634.             ren       180                       125, 129, 140, 141, 142,
  21635.             rename    15, 65,  66,  83,         165
  21636.                180, 222                      Setenv variables    1,  13,
  21637.             repeat statement    90,             53, 54,  111, 112,  113,
  21638.                139, 143                         117, 125, 157, 158, 159,
  21639.             Restrictions   132                  165
  21640.             return statement    93,          setkey statement    131,
  21641.                123, 131, 139                    142
  21642.             reverse   116                    setrows   177, 235
  21643.             rm   29, 30, 177                 SHELL     53,   158,   159,
  21644.             rmdir     83, 177, 180, 228         160, 169, 170
  21645.             rotd      33,   175,   186,      Shell escape character   52
  21646.                196, 224, 225, 229               , 72
  21647.             round()   58, 171                Shell scripts       96,
  21648.             safecopy()     65                   125, 133
  21649.             safedel()      66                shift statement     140
  21650.             saferename()   65                sin()     171
  21651.             safexcopy()    65                Single quotes       71, 72,
  21652.             samepath()     92, 171              152, 209, 234
  21653.             samples   11, 12, 17             sinh()    171
  21654.             samples directory   4,   5,      sizeof.csh     127
  21655.                6, 7,  71, 85,  93, 121,      sleep     104,  175,   235,
  21656.                125                              251
  21657.             savehist       117,    160,      source statement    4,  65,
  21658.                169, 183                         98, 99,  100, 143,  175,
  21659.             Scheduling     26, 103, 212         180, 222, 236
  21660.             Screen colors       17,          Special devices     147
  21661.                111, 115                      split     38, 177, 236
  21662.             screen$   147                    sqrt()    75, 123, 171
  21663.             scriptname     97,     130,      start     181, 241
  21664.                163, 169                      Start Programs      5,   8,
  21665.             SDK 1.06       3                    13,  15,  17,  23,  112,
  21666.             Seamless Windows    237             116, 184
  21667.             Search path    3,  4,  111,      startup.cmd    112
  21668.                113, 124, 158, 161, 168,      startup.csh    4,  5,   11,
  21669.                169                              14, 15,  24, 62, 65, 93,
  21670.             Search/replace operations           111, 112, 117, 134, 183
  21671.                35, 68, 154, 231              startwin       177, 237
  21672.             sed       35, 36, 177, 229,      Statement lists     86, 143
  21673.                231                           Statement relationships       
  21674.             Semicolon      75, 76, 126,         144
  21675.                127, 144                      status    43, 85,  97,  98,
  21676.             Separate arrow keys      15         126, 127, 162, 163, 164,
  21677.                0                                167, 170, 175, 225
  21678.             serial archive media     19      Stdout and Stderr   42
  21679.                7, 199, 200, 203              stmtnumber     133,    163,
  21680.             Serial execution    85, 144         164, 165, 170
  21681.             Serial ports   147               Stream editor       35,
  21682.                                                 177, 229
  21683.  
  21684.  
  21685.  
  21686.                                       Page 343
  21687.  
  21688.      Index
  21689.  
  21690.  
  21691.             String functions    172          Time critical       207
  21692.             String search       34,          Timestamps     29, 246
  21693.                176, 208                      Timezone       159, 170
  21694.             strings   38, 177                title bar      3,  8,  111,
  21695.             strlen()       172                  112
  21696.             Subscripting errors      97      touch     31, 43, 177, 246
  21697.             Substitution modifiers   15      tr   38, 177, 231, 247
  21698.                4                             Translate characters     24
  21699.             substr()       172                  7
  21700.             sum       177, 239               Trigonometric functions       
  21701.             switch statement    88,             171
  21702.                130, 138, 143, 148, 179       ts.csh    127
  21703.             SWITCHCHARS    28,     113,      type      181
  21704.                114, 158, 170                 Type conversions    81
  21705.             System files   30,     116,      TZ   159, 170, 244
  21706.                146, 158, 170, 216            unalias statement   140
  21707.             SYSTEMDIRS     116,    158,      unbuffered     184
  21708.                170, 216                      unhash    14,   175,   210,
  21709.             SYSTEMFILES    116,    158,         227, 248
  21710.                170, 216                      uniq      177, 249
  21711.             Tab character       152          UNIX      28, 111
  21712.             TABS      4,  12,  37,  38,      unlocal statement   65, 66,
  21713.                44, 53,  113, 125,  158,         131, 141
  21714.                170, 177, 211, 218, 219,      unproc statement    14, 91,
  21715.                240, 241                         131, 139
  21716.             Tagged expressions       35      unset statement     55, 140
  21717.                , 36                          unsetenv statement       55
  21718.             tail      37,   113,   158,         , 140
  21719.                177, 241                      unsetkey statement       14
  21720.             tailstatus     117,    162,         2
  21721.                170                           until statement     90, 139
  21722.             tan()     171                    upper()   23, 115, 172
  21723.             tanh()    171                    User-Defined Colors      11
  21724.             TAPE      158, 170                  5
  21725.             Tape archive format      24      Variable substitutions   56
  21726.                2                                , 59, 115, 153
  21727.             tar       115,  157,   159,      Variables      1,  23,  26,
  21728.                167, 170, 177, 199, 203,         53, 55, 58, 76, 94, 105,
  21729.                204, 242, 243, 244               107, 113, 115, 117, 129,
  21730.             tee       177, 246                  133, 134, 137, 140, 141,
  21731.             Telex     21                        160, 219
  21732.             Text-windowable                  ver       178
  21733.                applications     13, 14,      verbose   162,  170,   238,
  21734.                83, 103, 217                     253
  21735.             threadid       98, 99, 164,      verify    175, 200, 249
  21736.                170                           Vertical Tab   152
  21737.             Threads   1, 4, 43, 54, 55,      viopaste.c     127
  21738.                91,  97,  98,  99,  105,      vl   181
  21739.                106, 107, 108, 133, 140,      vol       16, 32,  83, 113,
  21740.                141, 144, 160, 161, 162,         178, 181, 250
  21741.                163, 164, 165, 170, 175,      Volume labels       176,
  21742.                207, 212, 225, 236, 251          213
  21743.             time      86, 87,  91, 123,      w    181
  21744.                143                           wait      175, 181, 251
  21745.  
  21746.  
  21747.  
  21748.                                       Page 344
  21749.  
  21750.                                                                            Index
  21751.  
  21752.  
  21753.             wc   41, 129, 178, 251
  21754.             weekday.csh    127
  21755.             whereis   44, 91,  92, 124,
  21756.                133, 178, 251
  21757.             while statement     90,
  21758.                139, 143
  21759.             white     116
  21760.             Wildcard characters      61
  21761.                , 71, 79, 138, 152
  21762.             Wildcarding    1,  15,  19,
  21763.                26, 35,  61, 62, 64, 65,
  21764.                66, 75,  79,  113,  118,
  21765.                125, 132, 137, 139, 146,
  21766.                148, 149, 161, 162, 168,
  21767.                169, 179, 180, 181, 207
  21768.             winerror.csh   127
  21769.             WinSetTitleAndIcon       11
  21770.                2
  21771.             WinVersion     160, 170
  21772.             Word selections     67
  21773.             Workplace Shell     18
  21774.             Write verification       24
  21775.                9
  21776.             WriteFiles     46
  21777.             xcopy     15, 65,  66,  83,
  21778.                181
  21779.             xd   178, 252
  21780.             yellow    116
  21781.             Zero-length files   146
  21782.  
  21783.  
  21784.  
  21785.  
  21786.  
  21787.  
  21788.  
  21789.  
  21790.  
  21791.  
  21792.  
  21793.  
  21794.  
  21795.  
  21796.  
  21797.  
  21798.  
  21799.  
  21800.  
  21801.  
  21802.  
  21803.  
  21804.  
  21805.  
  21806.  
  21807.  
  21808.  
  21809.  
  21810.                                       Page 345
  21811.  
  21812.      Index
  21813.  
  21814.  
  21815.             
  21816.  
  21817.  
  21818.  
  21819.  
  21820.  
  21821.  
  21822.  
  21823.  
  21824.  
  21825.  
  21826.  
  21827.  
  21828.  
  21829.  
  21830.  
  21831.  
  21832.  
  21833.  
  21834.  
  21835.  
  21836.  
  21837.  
  21838.  
  21839.  
  21840.  
  21841.  
  21842.  
  21843.  
  21844.  
  21845.  
  21846.  
  21847.  
  21848.  
  21849.  
  21850.  
  21851.  
  21852.  
  21853.  
  21854.  
  21855.  
  21856.  
  21857.  
  21858.  
  21859.  
  21860.  
  21861.  
  21862.  
  21863.  
  21864.  
  21865.  
  21866.  
  21867.  
  21868.  
  21869.  
  21870.  
  21871.  
  21872.                                       Page 346
  21873.