========================================================================
This is the unmodified README from Paul Kranenburg's release of strace
for SunOS 4.1.x.  Some of the notes and instructions are no longer valid
however the file has been retained for its historical value. -- jrs
========================================================================

/*
 * @(#)README	2.4 92/01/21
 *
 * Copyright (C) 1991 Paul Kranenburg.
 *
 * Please send comments, enhancements or any other useful ideas to
 * the address at the end of this file.
 *
 */

strace(1) is a system call tracer for Sun(tm) systems much like the
Sun supplied program trace(1). strace(1) is a useful utility to sort
of debug programs for which no source is available which unfortunately
includes almost all of the Sun supplied system software.

Like trace(1), strace displays each system call and its arguments as it
is invoked by the traced process, but tries to do a better job of
decoding the arguments, displaying them in symbolic format whenever
possible. Passed structures/character arrays are read from the process'
address space and displayed in an appropriate format.

It is also possible to instruct strace to trace child processes as
they are created by the fork(2) system call. However, this is slightly
involved for two reasons: 1) the trace flag is cleared in the child
process by the fork system call, so we must make a special effort to
gain control of the child (see NOTES below), 2) our tracing manipulations
of the child may interfere with a possible wait(2) system call executed
by the (also traced) parent process. In this case we don't allow the parent
to continue until one of its children enters a state that may cause the
parent's wait(2) call to return.


NOTES.

o	Not all system calls have been implemented yet as described
	above (see dummy.h for a list), these calls only have their args
	displayed as hex numbers.

o	The program draws heavily on Sun's extensions to the ptrace(2)
	system call.

o	This release is based upon SunOS 4.1.1. The syscall list (syscall.h)
	and ioctl's (ioctlent.m4) are probably most critically dependant
	on the OS version (see also /sys/os/init_sysent.c).
	You may have to edit `ioctlsort.c' and/or `ioctlent.m4' to get
	`ioctlsort.c' to compile with your suite of system header files.

o	The way in which child processes are caught and attached to after
	the fork() call is Sparc-specific (in fact it has the looks of a
	terrible hack). Also, this trick won't work with vfork(2).
	Enhancements are sollicited for.

o	Dynamically linked executables can be convinced to use the fork(2)
	system call in stead of vfork(2) by modifying their (internal)
	symbol table immediately after such a program is exec'ed. Be
	warned that programs which depend on vfork's peculiar semantics
	may not run as expected. Enable by the `-F' switch.


INSTALLATION.

	Edit the paths in the Makefile to suit your local system.
	Enter the usual make commands (`make debug' to enable the
	compiler `-g' flag).

	Not all sites have a complete set of include files, depending
	on the selected software categories at OS install time. The
	makefile tries to detect the presence of the Sunview category,
	if other files are missing you may have to edit `ioctlent.h'.


COMMENTS TO:

	P. Kranenburg
	Department of Computer Science
	Erasmus University Rotterdam
	P.O. Box 1738
	NL-3000 DR Rotterdam
	e-mail: pk@cs.few.eur.nl