SnoopDos V1.2 -- Monitors AmigaDOS function calls
(C) Copyright Eddy Carroll, January 1991. 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:<name>
in the SnoopDos window, then a program is trying to access an environment
variable called <name>.
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.
AUTHOR
Eddy Carroll
Email: ecarroll@maths.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.
