TRASH

Section: User Commands (1)
Index Return to Main Contents

NAME

trash - trace system calls

SYNOPSIS

trash [ -ABCFHILMNPRSTVW ] [ -a argc ] [ -d fd ] [ -f executable ] [ -h history_length ] [ -o outfile ] [ -v ] [ command ]

DESCRIPTION

trash simulates the specified command (default: a.out) until it exits. A line of information is written to a duplicate (as in dup(2)) of the standard output immediately after each system call returns.

OPTIONS

-A: all - show all data in read(2) and write(2) arguments and results. Normally, only the first 32 bytes are shown. Also show the argv and envp vector arguments to execve(2).
-B: book - under the -I option (see below) print the number of the page in The Book ("MIPS RISC Architecture" by Gerry Kane) where may be found a description of the simulated instruction.
-C: C-like - show only assignments to registers and memory when used with the -M and -R options.
-F: follow - follow calls to execve(2) by execution of another instance of trash.
-H: histogram - trash will count the number of references to the simulated program's text space (in 4KB quanta) and will print this information whenever it simulates an execve(2), an exit(2) or when the simulator exits.
-I: instruction - print a line describing each MIPS instruction in a uniquely informative yet idiosyncratic format.
-L: line - do not make output line buffered.
-M: memory - print a line describing each (simulated) memory access.
-N: number - show the number of (simulated) instructions executed since the previous system call and the total number of instructions simulated so far.
-P: predisplay - print a line describing each system call before it is executed.
-R: register - print a line describing each (simulated) register access.
-S: syscall - do not print a line describing each system call after it is executed. If this flag is not present then a line is printed describing each system call after it is executed.
-T: time - show the number of microseconds of system time that elapse during each system call.
-V: verbose - print even more output.
-W: overwrite - do not truncate the output file before appending to it.
-a argc: The first argc trailing arguments are to be taken as the argument vector for the simulated process. The next trailing argument is to be ignored. The remaining trailing arguments are to be taken as the environment strings of the simulated process. (This feature is intended for trash's own internal use under the -F option.)
-d fd: Write trash's output to file descriptor fd. (This feature is intended for trash's own internal use under the -F option.)
-f executable: An unambiguous specification of the file that should be read to obtain the initial process image. Without this option trash will search for the file indicated by the first trailing argument using the same algorithm as execvp(2) and execlp(2).
-h history_length: trash will maintain a history of the last history_length instructions and will print them whenever it simulates an execve(2), an exit(2) or when the simulator exits.
-o outfile: Write trash's output to outfile.
-v: version - print the version string and then exit(2).

CAVEATS

Under the bsd43 universe, most system calls relating to signals are recognised but silently ignored.

Under the bsd43 universe, the reception of signals by the simulated process is not implemented.

Most exceptions are ignored or handled crudely.

Attempts to access data at invalid (simulated) addresses or attempts to access data at valid (simulated) addresses but in invalid ways are detected but are handled crudely.

Under the bsd43 universe, the value returned by the geteuid(2-BSD) system call is actually the result of executing the geteuid(2-SysV) system call under the sysv universe.

Under the bsd43 universe, the value returned by the pipe(2-BSD) system call is actually the result of executing the pipe(2-SysV) system call under the sysv universe.

The passing of open file descriptors in ioctl(2) system calls (e.g. see I_FDINSERT in streamio(7-SysV)) is not (yet) supported.

Some system calls are not yet implemented.

Under the bsd43 universe, vfork(2-BSD) is (incorrectly) implemented as a normal fork(2-BSD), so programs that rely on the shared memory/state properties of the former will not simulate correctly.

Several MIPS instructions have not been implemented. These are currently: bgezal, bltzal, break, all coprocessor 0, coprocessor 2 and coprocessor 3 instructions and the following coprocessor 1 instructions: c.f, c.nge, c.ngl, c.ngle, c.ngt, c.seq, c.sf, c.ueq and c.un.

The simulator assumes that all the world is big-endian.

Under the sysv universe, profil(2-SysV), and hence executable profiling, is ignored.

To be simulated an executable file must be readable.

The setuid and setgid mode bits of executables are ignored.

The simulation of a process by trash is much slower than the normal execution of that process.

The getdtablesize(2-BSD) system call returns the same value as it would under normal execution, but the simulated process will actually appear to run out of file descriptors (EMFILE) at a slightly lower number.

Under the -F option the execve system call is not correctly simulated if the first (path) argument is a shared library.

AUTHOR

Bruce Janson
bruce@cs.su.oz.au

This document was created by man2html, using the manual pages.
Time: 06:18:01 GMT, December 12, 2024