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] SYNTAX for changing default switches or password: CHAINSAW {switch and new data} {password} (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 . 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: . 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: . 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 deletes, without prompts, entire branches of a directory tree. Syntax: CHAINSAW {path to base directory} {password} {switches} or CHAINSAW (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 and its subdirectories are probably damaged. Occurs when the user presses Ctrl + Break or Ctrl + C. Chainsaw deleted file and removed 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 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: 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: 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: . 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: 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 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.