SnoopDos V1.0 -- Monitors AmigaDOS function calls (C) Copyright Eddy Carroll, September 1990. Freely Distributable. INTRODUCTION Have you ever wondered why a particular program won't seem to run? It could be looking for some special files which you've forgotten to install in the appropriate place. SnoopDos was designed to let you resolve situations like this, though it's probably useful for other things too. For those who don't like long instruction files, simply run SnoopDos with no options, then run a few application programs and look at the output displayed in SnoopDos's window. Interesting, eh? For those who'd like a more detailed explanation, read on... When you start SnoopDos, it opens a console window. In this window appears details of all calls made by any program on the system to the CurrentDir(), DeleteFile, Execute(), LoadSeg(), Lock() and Open() functions in the AmigaDOS library. The exception (as usual) is any program written in BCPL; this includes most of the commands in the C: directory. SnoopDos will tell you about all attempts to load libraries, devices and fonts. It will also tell you if a program looks for a specific file (for example in S:) or a specific disk volume or directory. This can be very useful when you're playing with new software which may require certain fonts or other support files. An unexpected bonus is that since AmigaDOS environment variables are stored as files, SnoopDos will tell you the names of any environment variables a program tries to read; if you see references to ENV: in the SnoopDos window, then a program is trying to access an environment variable called . USAGE When you start SnoopDos, it automatically detaches itself from the CLI and runs in the background. You can specify a number of options on the command line, either at this time or later on by running SnoopDos again. Each option can be given in lower case or upper case to respectively enable or disable that setting. Alternatively, you can follow the option by `1' or `0' which has the same effect. So, `-d' and `-d1' both enable the "Monitor DeleteFile()" option, whereas `-d' and `-d0' both disable that option. Without further ado, here's an explanation of each setting: -a Normally, SnoopDos uses different colours when displaying messages, to allow events to be easily distinguished from each other. You can force SnoopDos not to use any colour by disabling this option. This can be useful if you only have a 2-colour workbench. If SnoopDos is sending its output to a file, it turns off this option by default (but you can turn it back on again if you like). -c When this option is enabled, SnoopDos prints details of all calls to the CurrentDir() function. A program calls CurrentDir() when it wants to change its current directory to somewhere else. Note that no result is displayed for this function, since AmigaDOS does not allow for the possibility of it ever failing. -d This option allows you to see all calls to the DeleteFile() function, which is called whenever a program wants to delete a file. This can be useful with unknown programs, to make sure that they don't do anything nasty (though in fairness, there are much more effective ways for a rogue program to do damage than by deleting a few files). -f When enabled, this option causes SnoopDos to print out the full path names for files. For example, if a program's current directory is SYS:TOOLS and it tries to open a file called FOO, then the filename would be displayed as SYS:TOOLS/FOO. Normally, it would just be displayed as FOO. Filenames which are so expanded are prefixed by a `>' character. Filenames which already included a full path specification don't have this prefix. This allows you to determine if the calling program specified the full path or not. -g This option enables or disables the monitoring of AmigaDOS's LoadSeg() function. This is used to read in a binary loadfile and is most commonly used for loading in libraries, devices, fonts and handlers, and by third-party DOS shells to load in external commands. -l This option enables or disables the monitoring of AmigaDOS's Lock() function. Programs usually call this function to see if a particular file exists, or as a prelude to some more sophisticated operation on the file. -m This option allows SnoopDos to be activated or deactivated while still leaving it running. It is included merely for completeness; a much easier way to achieve the same affect is to type CTRL-D or CTRL-E in the SnoopDos window. -o This option enables or disables the monitoring of AmigaDOS's Open() function. Whenever a program wants to open a file for reading or writing, it calls this function. -w If several tasks try to call a particular DOS function at the same time, SnoopDos can only handle them one at a time. Normally, what will happen is that the other tasks speed on without waiting for SnoopDos and you see a warning message saying that some function calls were missed (this doesn't happen very often anyway). When the `-w' option is enabled however, SnoopDos will make all the different tasks queue up and take their turn. There is one important consequence of this: if a program tries to access a file on a volume not currently mounted (causing AmigaDOS to display a "Please insert volume xyzzy" requester), then SnoopDos will print out the details about the file requested but not whether the request succeeded or not; it can't do this until you respond to the requester. In the meantime, other tasks may now be trying to call AmigaDOS. For example, if you might try to pop open a new CLI with Dmouse or PopCLI, so that you can do an ASSIGN to fake the requested volume. All these tasks will have to wait until the original DOS call has been completed. Since this can confuse things (though only for the user), the option is disabled by default. You should only need it if you have to be absolutely sure of catching every action made by several tasks. -x This option enables or disables monitoring of Execute() calls. Unlike most other DOS function calls, the return value from the Execute() is NOT displayed; this is because when an Execute suceeds, the command being executed will most likely making AmigaDOS calls of of its own and if SnoopDos was waiting for Execute() to return, it would skip printing these out. Some forms of Execute() will appear to have no associated command to execute. This is normal, and occurs when a program redirects command input from another file. By default, Snoopdos operates as if you had started it with: SnoopDos -a1 -c1 -d1 -f0 -g1 -l0 -m1 -o1 -w0 -x1 or for those who prefer to use the other command format: SnoopDos -a -c -d -F -g -L -m -o -w -x There are four additional options as well, which cause immediate actions to be performed. These are: -h Prints out a help screen for SnoopDos. Actually, typing any unrecognised garbage after SnoopDos prints the help screen. -q Sends a message to the version of SnoopDos currently running telling it to remove itself. This is one way to quit SnoopDos, the other way being to type CTRL-C in its window. -r Prints out a brief report giving all the current settings for SnoopDos (eagle-eyed users may spot a striking resemblance between this display and the middle section of the help screen :-). Note that all other command line options are ignored when you use -r. -z Allows you to specify an alternative output file for SnoopDos to send messages to. The filename can follow immediately after the -z, or you can leave a space if you like. There are several uses for this function. First of all, you can use it to change the location of the SnoopDos window when it opens, by specifying a filename like -zCON:0/0/640/60/SnoopDos) (for a very short window). You should always make sure the window is at least 77 columns wide or the output will look pretty messed up. If you specify -zSER: or -zAUX: then SnoopDos will send output to the serial port at the baud rate specified in Preferences. AUX: is slightly preferable to SER: since SnoopDos will then recognise the CTRL-C, CTRL-D and CTRL-E characters when typed on the remote terminal. If you are using a colour ANSI terminal, you may like to re-enable colour by specifying `-a' in conjunction with this option. Finally, you can of course redirect output to a normal AmigaDOS file. You would only want to do this if you wanted to keep a permanent record of what went on on your system. This could be useful if you allow remote access to your Amiga and want a record of what people do on your system. THE SNOOPDOS WINDOW The SnoopDos window is divided into a number of columns, as follows: Process name The name of the process (or CLI command) that is executing the DOS call in question. If the DOS call is nested (see Res. below) then the process name will be prefixed by '> '. Func The function being executed (Open, Lock or Load). Open is printed in white, Lock in orange and Load in black, to allow rows to be quickly identifed at a glance. (Of course, if you've changed your Preferences, the actual colours may be different.) Other values which can appear here are Exec (for Execute), CD (for CurrentDir) and Del (for DeleteFile). Filename The name of the file being accessed. Remember that when the `-f' option is enabled, this will be prefixed by a `>' character if the filename displayed was expanded by SnoopDos to include the current directory of the calling process. Mode For Open(), this is OLD if an existing file is being opened or NEW if a new file is being opened. For Lock(), this is SHAR if the lock is a shared lock (i.e. several processes can access the same file) or EXCL if it is an exclusive lock (only this process can access the file). It remains empty for LoadSeg(). Res. The result of the DOS call. This is either `Okay' in white or `Fail' in orange. In general, you learn much more from the `Fail' entries (i.e. the things the program tried to find but couldn't). Occasionally, you may see a `>>>>' appearing here. This happens if some other program has also patched DOS library in such a way that the function currently being called calls another DOS function itself. One such program is Rez, which tries to open a program file for reading if you LoadSeg() it. In this case, the `>>>>' indicates that DOS calls are being nested. The DOS calls which are nested will have the associated process name prefixed by `> ' when they are displayed. `> (Done)' is displayed when the top level DOS function exits, and the exit status is displayed on the same line in the Res. column as normal. You can type several keys into the SnoopDos window. CTRL-C will terminate SnoopDos. CTRL-D will disable monitoring temporarily (and print a brief message to that effect); CTRL-E enables it again. Pressing Space or any other key will pause the output to the window, as in a CLI window. Press BackSpace to continue. Note that if you have the `-w' option enabled and you pause the output, all functions for which monitoring is enabled will cause the calling process to go to sleep until you restart output again. When SnoopDos wants to quit, it makes sure that nobody else has patched the DOS library after it. If something has, SnoopDos will refuse to exit immediately. Instead, it will check approximately every 5 seconds to see if it is safe to exit and as soon as it can, it will. HISTORY Version 0.9, May 28th 1990. Initial Beta release. No doubt people will find lots of bugs. Version 0.91, May 29th 1990. Silly bug meant Snoopdos couldn't open its console window unless Conman was installed. Now fixed. Improved the way DOS library is patched to make it somewhat more robust (it now works properly with UnixDirs). Version 0.92, May 31st 1990. Strange bug seemed to manifest itself when Rez was used; the first time a resident program was loaded, the display got messed up. Turns out that Rez calls Open() from within LoadSeg(). Such nesting of DOS calls is now indicated by prefixing the process name printed for any nested operations with a '>'. When the nesting is completed, '> Done' is displayed. Version 0.93, June 2nd 1990. Added -X option to monitor Execute() calls and reworked assembly language glue a bit to make it easier to modify in future. Version 1.00, 9th September 1990. First public release. After unexpectedly being sent to the US for the summer (new job), I finally got around to tidying it up. New features include monitoring of DeleteFile() and CurrentDir(), support for alternative devices/files (such as the serial port), colour now optional, a few other cosmetic changes. AUTHOR Eddy Carroll Email: ecarroll@vax1.tcd.ie Phone: +353-1-874540 Snailmail: The Old Rectory, Delgany, Co. Wicklow, Ireland. DISTRIBUTION SnoopDos may be freely distributed as long as no charge is made other than to cover time and copying costs. If you want to include SnoopDos as part of a commercial package (somehow I doubt it but it never hurts to mention :-) then contact the author listed above. Fred Fish is specifically given permission to include SnoopDos in his fine disk collection.