README for Alpha-trace (Thu Dec 09 20:04:19 EST 1993)

This is a version of trace (otherwise known as truss on systems
such as Solaris 2.x) for the Alpha running OSF/1. Check the man page for
detailed instructions on using this program. Basically it's very easy -
just use 'trace program' or 'trace -p pid'. Output is normally sent to
stderr, unless the '-o output_file' option is used. See the manual page
for further details.

This program was initially written as a quickie piece of code - since then
its been improved incrementally, and while it is now getting quite polished,
its still not at the same level as 'truss' or 'strace'.

Any additions you wish to make (especially customised output routines
for various system calls - theres plenty to go around :-) are more than
welcome - please send them to me so that everyone can benefit.

To use this program, you must mount the /proc filesystem, however only
do this is you are not too worried about security (there are bugs which
this program can easily highlight). To use the /proc system, either
mount manually with

mount -t procfs /proc /proc

or add the following line to /etc/fstab:

/proc /proc procfs rw 0 0

Note that this security problem has been fixed in DEC OSF/1 V1.3 and
that currently (in V1.2) this trace program no longer allows simple
exploitation of the hole.

Installation couldn't be simpler - just type make and you'll end up
(hopefully) with a 'trace' binary.

The original version of this program was done by James Bonfield
(jkb@mrc-lmb.cam.ac.uk) - the OSF/1 and Alpha community have benefitted
greatly from this work. As he was unable/unwilling to support this code,
I took his version, and have modified it extensively and I'm now looking
after it. Any bug reports, enhancements, or even just a note saying
whether it works for you, can be sent to me at the address below.

    Share & Enjoy!

Anthony Baxter <anthony@aaii.oz.au>
Australian Artificial Intelligence Institute, 
1 Grattan St, 
Carlton, Victoria
Australia  3053.

Notes:

To add a customised output routine, you must do several things:

1) you will need to write two functions. One is to print the system
   call name and arguments, and one to print the return value and any
   other 'post-system-call' info you wish to print.
   A template for these functions is in print_template.c

2) Add the name of the two functions to the correct system call(s) in
   sysname.c

3) Add prototypes for them to trace.h, and the file to the Makefile.

4) test it, then mail the completed file to me, so I can add it to 
   the source archive. :-)

