L---+---T1----+-T--2----T----3--T-+----4T---+---T5----+-T--R
.X:10
.XT:3
.XB:2
.H:
.H:
.H:
.F:
.F:
.F:
.F:























                          CHAINSAW

           A command line driven directory pruner

             Public Domain, 5/24/93, Ted Davis

                        Version 5.3

2
.X:10
.XT:3
.XB:2
.H:...CHAINSAW: overview
.H:
.H:
.F:
.F:
.F:
.F:...$$$...
CHAINSAW is a command line driven directory pruner.  It does 
not stop for user confirmation and can, therefore, readily 
be used from batch files.  It can generate comprehensive 
reports of its actions.

       It provides optional password protection to prevent 
casual prowlers from using it to accidentally (or 
intentionally) trash a disk or directory.  

       CHAINSAW is a cleaning tool, useful for a variety of 
tasks from cleaning out the \temp directory of files,
subdirectories, or both, to completely wiping an entire disk 
during reconfiguration for a new user.  This program is 
potentially destructive (as is FORMAT) and is intentionally 
somewhat difficult to use in its most destructive modes.  It 
is intended mostly for technicians, system administrators, 
and power users.  It is NOT intended for novice users, who 
are advised to leave it strictly alone. 

       The command line contains the complete path, 
including drive, to the directory node at which the pruning 
is to occur, a password (optional) and control switches 
(also optional). Switches are provided to allow the program 
to delete the files in the starting directory, and to remove 
that directory, as well as all the subdirectories and their 
contents, or just the subdirectories.  Other switches enable 
operation on the root directory or network drives.  Another 
group of switches control which of the program's messages 
will be written and whether they go to STDOUT or STDERR.  
Still other switches, used with a somewhat different syntax, 
allow changing the password and default switches.


       CHAINSAW is FREEWARE, placed in the public domain 
5/24/93 by the author, Ted Davis: it comes with absolutely 
no warranty and the user's only recourse is refund of the 
purchase price, which is nothing.  If you use this program, 
you do so on your own responsibility.  If you don't want to 
do that, erase your copy of the program RIGHT NOW. 


       There is no formal support for the program, but you 
do get the source code.  The author is not in a position to 
provide support, but comments are welcome, as are 
suggestions for improvements.  Since addresses and phone 
numbers tend to change, but CompuServe ID numbers are 
forever, I prefer to be contacted via CIS E-mail at 
73500,2314 (but do not expect a quick reply).  If you find 
this program useful, please let me know how you are using 
it, what features you use (and never use), etc.  I know how 
I use it and how my beta testers use it, but the program has 
a lot more in it that we routinely use.
3
.H:...CHAINSAW: syntax, switches
.H:
.H:
SYNTAX (most cases):

CHAINSAW {drive:path} {password} [switches] <Enter>

SYNTAX for changing default switches or password:

CHAINSAW {switch and new data} {password} <Enter>

(No matter what, the password must be the second item in the 
command tail, unless suppressed.)

The default password can be found elsewhere in this manual.

The program responds to Ctrl + C and Ctrl + Break by 
aborting with an ERRORLEVEL of 3 and a warning that some 
damage may have been done to the given directory branch.

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

.H:...CHAINSAW: switches
.H:
.H:
SWITCHES, general:
Switches are introduced by a '/' or '-' character and 
everything in the tail following the marker (except as noted 
above) is considered a switch character or delimiter.  The 
acceptable delimiters are '/', '-', ',', ';',  space, and tab.
Incorrect or stray characters in the command tail cause the 
program to bomb with an "if you don't know what you are 
doing, don't do it" message.

       In the following sections, the default switches are 
marked with an '*'. 

       Switches are processed in the order encountered, 
defaults first, then those from the command tail, which can, 
therefore, override the defaults.


SWITCHES, permission:
These enable or disable operations and locations.

f      Enables deletion of files in the starting directory.  
       It is used to completely clean out a directory rather 
       than just empty and remove its subdirectories.

F  *   Disables deletion of files in the starting directory.  
       It is used to empty and remove the subdirectories of 
       the starting directory while leaving the files in 
       that directory intact.

g      Enables removal of the starting directory as well as 
       all its contents, files as well as subdirectories.

G  *   Disables removal of the starting directory; only its 
       subdirectories, and, optionally, files will be 
       deleted.

4
n      Enables operations on network drives.

N  *   Disables operations on network drives.

p      Enables deletion of read-only, hidden, and system 
       files in all permitted directories.

P  *   Disables deletion of read-only, hidden, and system 
       files in all directories.

r      Enables operations in, but not on, the root 
       directory, if it is the starting path.

R  *   Disables operations in the root directory.


SWITCHES, message control


?, h, or H
       Invokes the help screen, which is a VERY brief 
       syntax and partial switch reminder.  No password is 
       needed with this switch.

b      All messages are written to STDOUT, which can be 
       redirected to a file or device.

B  *   Directs messages to their default destinations:
       Fatal error messages to STDERR
       Non-fatal error messages to STDOUT
       Informational messages to STDOUT
       File and directory deletion messages are not printed.

d      Enables directory removal listing to STDERR.

D      Enables directory removal listing to STDOUT.

e      Directs all messages to STDERR (the screen), which 
       cannot be redirected.

E      Same as B.

l      Enables listing of deleted files to STDERR.

L      Enables listing of deleted files to STDOUT.

m      Directs all fatal and non-fatal error messages to 
       STDERR without affecting informational and deletion 
       messages.

M      Directs error messages to their default destinations.

5
o      Directs all fatal and non-fatal error messages to 
       STDOUT without affecting informational and deletion 
       messages.

O      Same as M.

s  *   Enables printing of a summary at termination.

S      Disables printing of the summary.

w  *   Turns the message output routine on.  This is needed 
       only if the default has been changed to W.

W      Turns the message output routine off.  It is used in 
       batch files instead of sending all the messages to 
       STDOUT and redirecting it to NUL.

x      Turns off file deletion failure messages. 

X      Turns off directory removal failure messages.


SWITCHES, default changing:

For all of these, except 'A', the new data string follows 
the switch character without any delimiter.  If a password 
is needed, it must follow the switch string and be separated 
from it by at least one space.  The switch and string should 
be the first command tail argument, the password, the 
second.  No more than one of these switches can be used at a 
time; the program terminates after processing the first one, 
without even looking to see if there are more (well, almost 
like that, it will process 'a' or 'A' even if the first 
switch is 'z' or 'Z').  Although the default changing syntax 
given above is the preferred form, it is possible to include 
these switches in a normal command tail, but it is a waste 
of effort since all that happens is the default change; the 
program will not change defaults AND prune the directory on 
the same pass.  Note: these write to the executable file, 
but they still work if you rename the working copy of the 
program.

a      Change default switch settings.  The string that 
       follows the 'a' must be a legal switch string, it may 
       contain '/' or '-' characters, but must not contain 
       delimiters, unless the string is quoted.  Anything 
       that would cause the string to be passed as more than
       one argument will cause an error (bad password). 

A      Resets the original default switches, the ones marked 
       with '*' in the preceding sections.

6
z      Changes the password to the string following the 'z'.
       The next argument must be the existing password, if 
       any.  This switch removes the password if the 'z' is 
       followed immediately by a space.  Lower case 'z' 
       clears the screen to remove the passwords from view.

.H:...CHAINSAW: switches, messages
.H:
.H:
Z      Exactly like 'z' except that upper case 'Z' does not 
       clear the screen.


------------------------------------------------------------
.H:...CHAINSAW: messages
.H:
.H:

MESSAGES, general:
On invocation, the program displays a copyright message to 
STDOUT (unless the default is changed or overridden).  On 
exit it displays a summary, the number of files deleted and 
of directories removed to STDOUT (unless...).  In between, 
it may or may not display some other message or list.  

       The messages texts are listed in alphabetical order 
within categories.  Variable text is indicated by <type>.  
The messages are not necessarily in exactly the same format 
as they are on the screen since the screen is assumed to be 
80 columns and this text file is 60 columns wide.  

       Note that file and directory removal list messages 
both begin with "... " and removal failure messages begin 
with "*** ".  This allows easy separation and sorting of the 
message stream with various utility programs.             

       The rather large number of switches controlling 
message destinations are to allow generation of report files 
with user determined contents.  A typical case would send 
the list of file deletions to redirected STDOUT, suppress 
directory deletion listing, and send everything else to the 
screen (STDERR); another would send the error messages to 
the file, information messages to the screen and suppress 
the deletion messages.  In some batch file applications, any
message would be useless and all display could be 
suppressed. 

7
MESSAGES, informational:

... Deleted file: <filespec>.

       Indicates that the named file was successfully 
       deleted.  This message must be specifically enabled 
       with the 'l' or 'L' switch.  It is invoked when the C 
       function 'unlink' succeeds.  

... Removed directory: <path>.

       Indicates that the named directory was successfully 
       removed.  This message must be specifically enabled 
       with the 'd' or 'D' switch.  It is invoked when the C 
       function 'rmdir' succeeds. 


CHAINSAW <version> deletes, without prompts, entire 
branches of a directory tree. 

Syntax: CHAINSAW {path to base directory} {password} 
{switches} or CHAINSAW <modification switch> <password> (The 
drive letter is required, trailing '\' is optional.  
Switches may be in /bde, /b/d/e, /b /d /e, /b,/d,/e, -bde, -
b-d-e, -b -d -e, etc. format, so long as the first one 
immediately follows a '/' or '-'.) 
    There are too many switches to define all of them here, 
but... /A restores default switches, /a changes them; 
b,B,d,D,e,E,l,L,m,M,o,O,s,S, w,and W control the way the 
program writes its messages (and what messages it writes).  
For the rest of the listed switches, lower case enables and 
upper case disables the feature: f,F - file deletion in the 
base directory; g,G - base directory removal; n,N - 
operation on network drives; p,P - deletion of read-only, 
hidden and system files; r,R - operation on the root 
directory; See CHAINSAW.DOC for details."

       The help screen is invoked by a '?', 'h', or 'H' 
       switch. 

CHAINSAW aborted by user!  
Directory <base path> and its subdirectories are probably 
damaged.
       Occurs when the user presses Ctrl + Break or 
       Ctrl + C.

Chainsaw deleted <number or "no"> file<s> and removed 
<number or "no"> directories.

       This is the summary message displayed at the end of 
       the program.  Its presence is controlled by the 's' 
       and 'S' switches.

8
CHAINSAW...New password installed.
       This is the success message from the 'z' and 'Z' 
       switches.  It indicates that no errors occurred 
       during the process of encrypting the new password and 
       writing the result to CHAINSAW.EXE.

CHAINSAW Version <version> is FREEWARE, Copyright 1992, Ted 
Davis. 
       This is the copyright message displayed when the 
       program is invoked.   The 'w' and 'W' switches 
       control its presence. 

New default switches installed.
       This is the success message from the 'a' switch.  It 
       indicates that there were no errors during the 
       process of writing the new switch string to 
       CHAINSAW.EXE.  It does not mean that the switch 
       string makes sense or will work.

Original default switches reinstalled.
       This is the success message from the 'A' switch and 
       means that the original list of default switches has 
       been written to CHAINSAW.EXE.


MESSAGES, error:
Let us hope that you see few or none of these (but you 
will).  Some of these are followed by the appropriate DOS 
error message which can be used to help determine the cause 
of the error (maybe, if you have enough DOS interrupt 
reference material and the message is meaningful).

*** Deletion of file: <filespec> failed.
       'unlink' failed to execute properly.  The reason is 
       likely to be obscure, perhaps a DOS error, the 
       drive is not erasable or the disk is write protected, 
       or the file is locked by another program on the 
       network. 

*** Deletion of file: <filespec> failed.  Error: read-only, 
hidden, or system.
       The file attributes included one or more of those 
       requiring special permission from the user for 
       deletion.  The 'p' switch enables their deletion and 
       prevents this message, except on write protected or 
       read-only drives.

*** ERROR: <message>.
       This follows another message and provides what the 
       makers of DOS and of Turbo C++ think of as helpful 
       explanations of a DOS interrupt function failure.  
       These messages are often useless, misleading, and/or 
       cryptic but may be helpful to DOS experts and power 
       users. 

9
*** Removal of directory: <path> failed.
       'rmdir' failed to execute properly.  The most likely 
       reason is that the directory, or one of its 
       subdirectories is not empty, perhaps due to hidden, 
       read-only, or system files that were not erased 
       because you did not use the 'p' switch or an erasure 
       failure.  


DOS 3.0 or later is required.
       This message is self explanatory; the only cure is to 
       upgrade your version of DOS, which you probably 
       should have done anyway when DOS 5.0 came out.

Memory allocation ERROR, CHAINSAW aborted.
       This means either that the directory tree has too 
       many subdirectories on the branch in work or that a 
       DOS memory allocation error occurred.  CHAINSAW 
       creates (and allocates memory for) a new instance of 
       the 'dirkiller' object for the base directory and for 
       each level of subdirectories within it.  This message 
       occurs when the 'new' operator fails.

Password incorrect of file read error... CHAINSAW aborted.
       The most usual causes are a typo in the password and
       omission of all or part of the command tail.  It can 
       also occur if CHAINSAW.EXE becomes corrupted or 
       cannot find itself.

Unable to change password.
       This means that there was an error writing the new 
       password to CHAINSAW.EXE, or in finding the existing 
       one in the file.  Make sure that CHAINSAW.EXE is not 
       marked read-only, that the disk is not write 
       protected, and if on a network, that you have write 
       permission for the directory in which it resides.  If 
       none of that helps, it will be necessary to start 
       over with an unmodified copy of the program as 
       distributed.    

Unable to change switches.
       This means that there was an error writing the new 
       switches to CHAINSAW.EXE, or in finding the existing 
       ones in the file.  Make sure that CHAINSAW.EXE is not 
       marked read-only, that the disk is not write 
       protected, and if on a network, that you have write 
       permission for the directory in which it resides.  If 
       none of that helps, it will be necessary to start 
       over with an unmodified copy of the program as 
       distributed. 

10
The calling syntax for CHAINSAW was incorrect...
If you do not FULLY understand the syntax and what the 
program does you should not attempt to use it.  This program  
DESTROYS ENTIRE BRANCHES OF THE DIRECTORY TREE.
If used incorrectly, it can do untold damage.
       This is the barf message: there was something on, or 
       missing from, the command line that the parser did 
       not like.  Its primary purpose is to discourage 
       browsers while protecting your hard disk(s).  In 
       practice, you will get it most often by forgetting 
       to include the entire command tail when invoking the 
       program: CHAINSAW <Enter> will get it for you.  The 
       absolute minimum command tail contains the complete 
       path, including drive, to the starting directory, and 
       unless you have turned off the password feature, the 
       password.

11
.H:...CHAINSAW: ERRORLEVELS, SAFETY
.H:
.H:

ERRORLEVELS:
CHAINSAW returns an exit code which can be read and acted 
upon by a calling batch file with the IF ERRORLEVEL test. 

       ERRORLEVEL == 0 - Normal termination: everything went 
                         OK, no problems. 
       ERRORLEVEL == 1 - aborted due to some internal error 
                         or command tail syntax error.
       ERRORLEVEL == 2 - ran to completion, but failed to 
                         delete one or more files or 
                         directories.  
       ERRORLEVEL == 3 - user aborted with Ctrl + Break or 
                         Ctrl + C. 
       ERRORLEVEL == 4 - HELP message was displayed.
       ERRORLEVEL == 5 - Password or default switches 
                         changed, message indicates success 
                         or failure.

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

SAFETY and SECURITY:

Most directory pruners either stop and demand confirmation 
from the operator before deleting anything (some prompt for 
everything) or are quick knock-offs that should never leave 
the authors hands.  CHAINSAW is neither.  It is thoroughly 
thought out and tested, and while it does not prompt for 
confirmation, it does have password protection to prevent 
unauthorized use and a rather elaborate set of switches to 
either protect or unprotect such critical areas as the root 
directory; read-only, hidden, and system files; and network 
drives.  For those (such as the target user) who are 
determined to make it easy for casual browsers to trash 
their hard disks, the password feature can be turned off, if 
you have the password.  NOTE: the default password is 
"password" (lower case, no quote marks).  I buried that here 
so that the potential user must at least scan the manual 
before using the program. 

       For those users who are concerned about viruses:
when released, the program was clean, and CIS has a very 
good reputation for virus free software.  Nevertheless,
the best possible protection is to read, understand, and 
recompile the source code.  It was written using Turbo C++ 
PRO (the PRO is important because the inline assembly 
requires TASM and TASM2MSG, which are included in the 
package) with the small memory model.  The only problems to 
be expected with other C++ compilers would be with library 
function names and the inline assembly code.  Most compilers 
have equivalent functions and many have some way to deal 
with inline assembly.  In case yours doesn't, you are on 
your own.  Versions after Beta 5.2 were compiled with 
Borland C++ for DOS.

12
.H:...CHAINSAW: more about
.H:
.H:

More about CHAINSAW:

Most of the code is pure C, but the real business of the 
program, recursion through the directory tree, file 
deletion, and directory removal uses a C++ class named 
'dirkiller' which consists of a data block and a 
constructor.  Construction of the object performs its work.  
When the active instance of dirkiller encounters a 
subdirectory, it creates a new instance of itself to process 
it.  Each instance is destroyed (and removed from memory) 
when it finishes.  This is not true recursion, it is in many 
ways better.  The network drive test is implemented mostly 
in assembly, and is built around DOS interrupt 0x21, 
function 0x44, subfunction 0x09 which reports whether a 
given drive is local or remote.  The source code is heavily 
commented, except for the password changing and reading 
functions.

       The program uses the small memory model, which 
accounts for some of the apparently unneeded code that 
processes the command tail arguments.  They seem to be 
represented by far pointers and cannot be passed to 
functions without a lot of trouble, or a different, and 
slower, memory model.

       This program grew out of a co-worker's need for a 
program to remove a bunch of subdirectories created by a 
batch file.  It needed to work from the batch file without 
operator intervention.  After a bit of research and a lot of 
thinking about the problem, I decided to write a generalized 
command line pruner for public distribution as freeware.  
Obviously, that requires both more features and at least 
some protection from accidental disk trashing.  It grew, and 
grew, and grew.  There are several more features that I 
would like to add, such as a switch to allow exclusion of 
specified sub-branches of the target directory, and another 
to exclude, as non-overrideable defaults, specified 
directories and branches (such as C:\ and C:\DOS); but I had 
to draw the line somewhere.  If there is a demand for them, 
I will produce a version with those, and/or other, features.  
If you want something really customized, I am willing to 
talk money. 

T.E.D.  1/11/92


13
                 Addenda 3/4/93 and 5/24/93

This program has been in almost daily use by a PC support 
group (over 50 PCs) for over a year.  Most of the bugs 
have been exterminated and usage patterns have formed and 
have been analyzed. There has been only one change to the 
dirkiller object in over six months, and it was rather minor 
(to handle the special case of removing an already empty 
directory (why anyone would use CHAINSAW instead of 
RD for that completely escapes me)).  

        The uses of the program fall into a few distinct 
classes:
l---+---l-----+-L--2----T----3--T-+----4T---+---T5----+-T--R
        1)      A password protected copy in the network 
                search path is used mostly to strip out old 
                installations of user software before 
                upgrade or reinstallation and to clean out 
                user's c:\temp directories that get filled 
                up with batch files left by DOSSHELL when 
                the user reboots without dropping the 
                program.  I took over a hundred out of one 
                professor's \temp directory.  CHAINSAW is 
                preferred because it cleans out the 
                directory completely, including removal of 
                subdirectories, which DEL *.*, with its 
                annoying "Are you sure" prompt doesn't do.

        2)      Unprotected copies in the technicians' 
                individual paths (ahead of the global copy) 
                are used frequently for the original purpose 
                of the program: to clean up after shuffling 
                files through a \temp directory. 

        3)      We use the same unprotected copies to delete 
                dead directories and unwanted program 
                installations, as after testing a new 
                program. 

        4)      An unprotected copy on the same floppy as a 
                batch file is used to remove everything 
                except authorized files from lab and student 
                machines.  The batch file marks the allowed 
                files as read-only and CHAINSAW is not 
                allowed to delete them.  It also writes a 
                report of what it removed and did not remove 
                to STDOUT which is redirected to a data file 
                on the floppy.  The DOS FIND service then 
                separates the removals and non-removals into 
                separate files for analysis.  The batch file 
                also cleans up after itself by removing the 
                read-only marks from those files that are 
                not supposed to be read-only.
14

        5)      I use it to strip entire drives down to the 
                volume label in preparation for installing a 
                new version of DOS and a set of standard 
                programs as part of a procedure for 
                refurbishing old machines for new users.

        6)      We also carry it around to non-networked lab 
                machines to clean up students working 
                directories after they graduate (or 
                otherwise leave).  A few of these machines 
                are networked - and we use our own copies or 
                the protected "public" copy instead of 
                carrying a floppy around. 

L---+----T----+----2----T----3--T-+----4T---+---T5----+-T--R

         The report generation code, on which I spent so 
much time, is used only during the pre-semester cleanup 
sweep.  The password feature is used only for the copy that 
anyone can access over the network (of course, the other 
copies are either kept filed away on floppies in drawers or 
are protected by our network login passwords).

         I cannot say that the program is perfect or 
bullet proof but, in over a year of use and testing, it has 
never removed anything it wasn't told to remove.  There have 
been malfunctions, but they have all been benign - they 
have resulted in something not being removed or the program 
refusing to do anything at all; these have all been fixed. 
See CHAINSAW.CPP for the version history.

         One or two last notes: I thought it was 
malfunctioning when it refused to remove c:\windows\fungame 
from my own machine at home.  I had momentarily forgotten 
that a SUBST was in effect for that directory (as drive F:).  
DOS refused to let CHAINSAW remove what it thought of as a 
root directory.  Even with the permission switch on, I got 
the general ERROR message with the explanation that access 
was denied.  I did once get a "Protected Mode Violation" 
error from Windows 3.1 (in standard mode on a PS2-30/286), 
but I get those all the time).  No, I will not explain why I 
am trying to support Windows and Windows apps with a brain-
damaged computer.   The program has not been tested under 
DOS 6.0; we were smart enough to pass on that one, so I 
don't have access to it.

T.E.D.
